MVCHandler.java
0001 /*
0002  * SPDX-License-Identifier: Apache-2.0
0003  *
0004  * Copyright 2008-2017 the original author or authors.
0005  *
0006  * Licensed under the Apache License, Version 2.0 (the "License");
0007  * you may not use this file except in compliance with the License.
0008  * You may obtain a copy of the License at
0009  *
0010  *     http://www.apache.org/licenses/LICENSE-2.0
0011  *
0012  * Unless required by applicable law or agreed to in writing, software
0013  * distributed under the License is distributed on an "AS IS" BASIS,
0014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0015  * See the License for the specific language governing permissions and
0016  * limitations under the License.
0017  */
0018 package griffon.core.mvc;
0019 
0020 import griffon.core.artifact.GriffonController;
0021 import griffon.core.artifact.GriffonModel;
0022 import griffon.core.artifact.GriffonMvcArtifact;
0023 import griffon.core.artifact.GriffonView;
0024 
0025 import javax.annotation.Nonnull;
0026 import java.util.List;
0027 import java.util.Map;
0028 
0029 /**
0030  * Base contract for classes that can manipulate MVC groups.
0031  * There are 4 types of methods used for instantiating a group:
0032  <ul>
0033  <ol>{@code createMVCGroup()} - creates a new group instance returning all members.</ol>
0034  <ol>{@code createMVC()} - creates a new group instance returning only Model, View and Controller members.</ol>
0035  <ol>{@code withMVCGroup()} - creates a new group instance and destroys it immediately after it has been processed by the callback.</ol>
0036  <ol>{@code withMVC()} - creates a new group instance and destroys it immediately after it has been processed by the callback.</ol>
0037  </ul>
0038  <p/>
0039  * It's worth mentioning that the value of the {@code mvcId} parameter must be unique otherwise a collision will occur.
0040  * When that happens the application will report and exception and terminate. This behavior can be configured to be more
0041  * lenient, by defining a configuration flag {@code griffon.mvcid.collision} in {@code Config}. <br/>
0042  * Accepted values are
0043  <ul>
0044  <ol>warning - reports the error but allows the application to continue. Destroys the existing group before continuing.</ol>
0045  <ol>exception - reports the error and terminates the application. this is the default behavior.</ol>
0046  </ul>
0047  *
0048  @author Andres Almiray
0049  @since 2.0.0
0050  */
0051 public interface MVCHandler {
0052     /**
0053      * Instantiates an MVC group of the specified type.<p>
0054      * MVC groups must be previously configured with the application's metadata
0055      * before they can be used. This registration process usually takes place automatically
0056      * at boot time. The type of the group can be normally found in the application's
0057      * configuration file.<p>
0058      * For example, with the following entry available in {@code Config.groovy}
0059      <p/>
0060      <pre>
0061      * mvcGroups {
0062      *     foo {
0063      *         model      = 'com.acme.FooModel'
0064      *         view       = 'com.acme.FooView'
0065      *         controller = 'com.acme.FooController'
0066      *     }
0067      * }
0068      </pre>
0069      <p/>
0070      * An instance of the "foo" group can be created as follows
0071      <p/>
0072      <pre>
0073      * MVCGroup fooGroup = createMVCGroup('foo')
0074      * assert (fooGroup.controller instanceof FooController)
0075      </pre>
0076      *
0077      @param mvcType the type of group to build.
0078      *
0079      @return an MVCGroup instance of the desired type
0080      *
0081      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0082      *                                                           configuration or if a group with the same mvcId exists already.
0083      */
0084     @Nonnull
0085     MVCGroup createMVCGroup(@Nonnull String mvcType);
0086 
0087     /**
0088      * Instantiates an MVC group of the specified type with a particular name.<p>
0089      * MVC groups must be previously configured with the application's metadata
0090      * before they can be used. This registration process usually takes place automatically
0091      * at boot time. The type of the group can be normally found in the application's
0092      * configuration file.<p>
0093      * For example, with the following entry available in {@code Config.groovy}
0094      <p/>
0095      <pre>
0096      * mvcGroups {
0097      *     foo {
0098      *         model      = 'com.acme.FooModel'
0099      *         view       = 'com.acme.FooView'
0100      *         controller = 'com.acme.FooController'
0101      *     }
0102      * }
0103      </pre>
0104      <p/>
0105      * An instance of the "foo" group can be created as follows
0106      <p/>
0107      <pre>
0108      * MVCGroup fooGroup = createMVCGroup('foo', 'foo' + System.currentTimeMillis())
0109      * assert (fooGroup.controller instanceof FooController)
0110      </pre>
0111      <p/>
0112      * MVC groups must have an unique name.
0113      *
0114      @param mvcType the type of group to build.
0115      @param mvcId   the name to assign to the built group.
0116      *
0117      @return an MVCGroup instance of the desired type
0118      *
0119      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0120      *                                                           configuration or if a group with the same mvcId exists already.
0121      */
0122     @Nonnull
0123     MVCGroup createMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId);
0124 
0125     /**
0126      * Instantiates an MVC group of the specified type with additional variables.<p>
0127      * MVC groups must be previously configured with the application's metadata
0128      * before they can be used. This registration process usually takes place automatically
0129      * at boot time. The type of the group can be normally found in the application's
0130      * configuration file.<p>
0131      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0132      * scenarios <ul>
0133      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0134      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0135      * on any MVC member of the group.</li>
0136      </ul>
0137      <p/>
0138      * For example, with the following entry available in {@code Config.groovy}
0139      <p/>
0140      <pre>
0141      * mvcGroups {
0142      *     foo {
0143      *         model      = 'com.acme.FooModel'
0144      *         view       = 'com.acme.FooView'
0145      *         controller = 'com.acme.FooController'
0146      *     }
0147      *     bar {
0148      *         model      = 'com.acme.FooModel'
0149      *         view       = 'com.acme.BarView'
0150      *         controller = 'com.acme.BarController'
0151      *     }
0152      * }
0153      </pre>
0154      <p/>
0155      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0156      * instance by creating the groups in the following way:
0157      <p/>
0158      <pre>
0159      * MVCGroup fooGroup = createMVCGroup('foo')
0160      * MVCGroup barGroup = createMVCGroup('bar', model: fooGroup.model)
0161      * assert fooGroup.model == barGroup.model
0162      </pre>
0163      *
0164      @param args    any useful values that can be set as properties on each MVC member or that
0165      *                identify a member that can be shared with other groups.
0166      @param mvcType the type of group to build.
0167      *
0168      @return an MVCGroup instance of the desired type
0169      *
0170      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0171      *                                                           configuration or if a group with the same mvcId exists already.
0172      */
0173     @Nonnull
0174     MVCGroup createMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType);
0175 
0176     /**
0177      * Instantiates an MVC group of the specified type with additional variables.<p>
0178      * MVC groups must be previously configured with the application's metadata
0179      * before they can be used. This registration process usually takes place automatically
0180      * at boot time. The type of the group can be normally found in the application's
0181      * configuration file.<p>
0182      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0183      * scenarios <ul>
0184      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0185      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0186      * on any MVC member of the group.</li>
0187      </ul>
0188      <p/>
0189      * For example, with the following entry available in {@code Config.groovy}
0190      <p/>
0191      <pre>
0192      * mvcGroups {
0193      *     foo {
0194      *         model      = 'com.acme.FooModel'
0195      *         view       = 'com.acme.FooView'
0196      *         controller = 'com.acme.FooController'
0197      *     }
0198      *     bar {
0199      *         model      = 'com.acme.FooModel'
0200      *         view       = 'com.acme.BarView'
0201      *         controller = 'com.acme.BarController'
0202      *     }
0203      * }
0204      </pre>
0205      <p/>
0206      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0207      * instance by creating the groups in the following way:
0208      <p/>
0209      <pre>
0210      * MVCGroup fooGroup = createMVCGroup('foo')
0211      * MVCGroup barGroup = createMVCGroup('bar', model: fooGroup.model)
0212      * assert fooGroup.model == barGroup.model
0213      </pre>
0214      *
0215      @param mvcType the type of group to build.
0216      @param args    any useful values that can be set as properties on each MVC member or that
0217      *                identify a member that can be shared with other groups.
0218      *
0219      @return an MVCGroup instance of the desired type
0220      *
0221      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0222      *                                                           configuration or if a group with the same mvcId exists already.
0223      */
0224     @Nonnull
0225     MVCGroup createMVCGroup(@Nonnull String mvcType, @Nonnull Map<String, Object> args);
0226 
0227     /**
0228      * Instantiates an MVC group of the specified type with a particular name.<p>
0229      * MVC groups must be previously configured with the application's metadata
0230      * before they can be used. This registration process usually takes place automatically
0231      * at boot time. The type of the group can be normally found in the application's
0232      * configuration file.<p>
0233      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0234      * scenarios <ul>
0235      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0236      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0237      * on any MVC member of the group.</li>
0238      </ul>
0239      <p/>
0240      * For example, with the following entry available in {@code Config.groovy}
0241      <p/>
0242      <pre>
0243      * mvcGroups {
0244      *     foo {
0245      *         model      = 'com.acme.FooModel'
0246      *         view       = 'com.acme.FooView'
0247      *         controller = 'com.acme.FooController'
0248      *     }
0249      * }
0250      </pre>
0251      <p/>
0252      * We can create two instances of the same group that share the same model instance in the following way:
0253      <p/>
0254      <pre>
0255      * MVCGroup fooGroup1 = createMVCGroup('foo', 'foo1')
0256      * MVCGroup fooGroup2 = createMVCGroup('foo', 'foo2', model: fooGroup1.model)
0257      * assert fooGroup1.model == fooGroup2.model
0258      </pre>
0259      <p/>
0260      * MVC groups must have an unique name.
0261      *
0262      @param args    any useful values that can be set as properties on each MVC member or that
0263      *                identify a member that can be shared with other groups.
0264      @param mvcType the type of group to build.
0265      @param mvcId   the name to assign to the built group.
0266      *
0267      @return an MVCGroup instance of the desired type
0268      *
0269      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0270      *                                                           configuration or if a group with the same mvcId exists already.
0271      */
0272     @Nonnull
0273     MVCGroup createMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull String mvcId);
0274 
0275     /**
0276      * Instantiates an MVC group of the specified type with a particular name.<p>
0277      * MVC groups must be previously configured with the application's metadata
0278      * before they can be used. This registration process usually takes place automatically
0279      * at boot time. The type of the group can be normally found in the application's
0280      * configuration file.<p>
0281      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0282      * scenarios <ul>
0283      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0284      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0285      * on any MVC member of the group.</li>
0286      </ul>
0287      <p/>
0288      * For example, with the following entry available in {@code Config.groovy}
0289      <p/>
0290      <pre>
0291      * mvcGroups {
0292      *     foo {
0293      *         model      = 'com.acme.FooModel'
0294      *         view       = 'com.acme.FooView'
0295      *         controller = 'com.acme.FooController'
0296      *     }
0297      * }
0298      </pre>
0299      <p/>
0300      * We can create two instances of the same group that share the same model instance in the following way:
0301      <p/>
0302      <pre>
0303      * MVCGroup fooGroup1 = createMVCGroup('foo', 'foo1')
0304      * MVCGroup fooGroup2 = createMVCGroup('foo', 'foo2', model: fooGroup1.model)
0305      * assert fooGroup1.model == fooGroup2.model
0306      </pre>
0307      <p/>
0308      * MVC groups must have an unique name.
0309      *
0310      @param mvcType the type of group to build.
0311      @param mvcId   the name to assign to the built group.
0312      @param args    any useful values that can be set as properties on each MVC member or that
0313      *                identify a member that can be shared with other groups.
0314      *
0315      @return an MVCGroup instance of the desired type
0316      *
0317      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0318      *                                                           configuration or if a group with the same mvcId exists already.
0319      */
0320     @Nonnull
0321     MVCGroup createMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args);
0322 
0323     /**
0324      * Instantiates an MVC group of the specified type.<p>
0325      * MVC groups must be previously configured with the application's metadata
0326      * before they can be used. This registration process usually takes place automatically
0327      * at boot time. The type of the group can be normally found in the application's
0328      * configuration file.<p>
0329      * For example, with the following entry available in {@code Config.groovy}
0330      <p/>
0331      <pre>
0332      * mvcGroups {
0333      *     foo {
0334      *         model      = 'com.acme.FooModel'
0335      *         view       = 'com.acme.FooView'
0336      *         controller = 'com.acme.FooController'
0337      *     }
0338      * }
0339      </pre>
0340      <p/>
0341      * An instance of the "foo" group can be created as follows
0342      <p/>
0343      <pre>
0344      * FooMVCGroup fooGroup = createMVCGroup(FooMVCGroup)
0345      * assert (fooGroup.controller instanceof FooController)
0346      </pre>
0347      *
0348      @param mvcType the type of group to build.
0349      *
0350      @return an MVCGroup instance of the desired type
0351      *
0352      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0353      *                                                           configuration or if a group with the same mvcId exists already.
0354      @since 2.11.0
0355      */
0356     @Nonnull
0357     <MVC extends TypedMVCGroup> MVC createMVCGroup(@Nonnull Class<? extends MVC> mvcType);
0358 
0359     /**
0360      * Instantiates an MVC group of the specified type with a particular name.<p>
0361      * MVC groups must be previously configured with the application's metadata
0362      * before they can be used. This registration process usually takes place automatically
0363      * at boot time. The type of the group can be normally found in the application's
0364      * configuration file.<p>
0365      * For example, with the following entry available in {@code Config.groovy}
0366      <p/>
0367      <pre>
0368      * mvcGroups {
0369      *     foo {
0370      *         model      = 'com.acme.FooModel'
0371      *         view       = 'com.acme.FooView'
0372      *         controller = 'com.acme.FooController'
0373      *     }
0374      * }
0375      </pre>
0376      <p/>
0377      * An instance of the "foo" group can be created as follows
0378      <p/>
0379      <pre>
0380      * FooMVCGroup fooGroup = createMVCGroup(FooMVCGroup, 'foo' + System.currentTimeMillis())
0381      * assert (fooGroup.controller instanceof FooController)
0382      </pre>
0383      <p/>
0384      * MVC groups must have an unique name.
0385      *
0386      @param mvcType the type of group to build.
0387      @param mvcId   the name to assign to the built group.
0388      *
0389      @return an MVCGroup instance of the desired type
0390      *
0391      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0392      *                                                           configuration or if a group with the same mvcId exists already.
0393      @since 2.11.0
0394      */
0395     @Nonnull
0396     <MVC extends TypedMVCGroup> MVC createMVCGroup(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId);
0397 
0398     /**
0399      * Instantiates an MVC group of the specified type with additional variables.<p>
0400      * MVC groups must be previously configured with the application's metadata
0401      * before they can be used. This registration process usually takes place automatically
0402      * at boot time. The type of the group can be normally found in the application's
0403      * configuration file.<p>
0404      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0405      * scenarios <ul>
0406      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0407      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0408      * on any MVC member of the group.</li>
0409      </ul>
0410      <p/>
0411      * For example, with the following entry available in {@code Config.groovy}
0412      <p/>
0413      <pre>
0414      * mvcGroups {
0415      *     foo {
0416      *         model      = 'com.acme.FooModel'
0417      *         view       = 'com.acme.FooView'
0418      *         controller = 'com.acme.FooController'
0419      *     }
0420      *     bar {
0421      *         model      = 'com.acme.FooModel'
0422      *         view       = 'com.acme.BarView'
0423      *         controller = 'com.acme.BarController'
0424      *     }
0425      * }
0426      </pre>
0427      <p/>
0428      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0429      * instance by creating the groups in the following way:
0430      <p/>
0431      <pre>
0432      * FooMVCGroup fooGroup = createMVCGroup(FooMVCGroup)
0433      * BarMVCGroup barGroup = createMVCGroup(BarMVCGroup, model: fooGroup.model)
0434      * assert fooGroup.model == barGroup.model
0435      </pre>
0436      *
0437      @param args    any useful values that can be set as properties on each MVC member or that
0438      *                identify a member that can be shared with other groups.
0439      @param mvcType the type of group to build.
0440      *
0441      @return an MVCGroup instance of the desired type
0442      *
0443      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0444      *                                                           configuration or if a group with the same mvcId exists already.
0445      @since 2.11.0
0446      */
0447     @Nonnull
0448     <MVC extends TypedMVCGroup> MVC createMVCGroup(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType);
0449 
0450     /**
0451      * Instantiates an MVC group of the specified type with additional variables.<p>
0452      * MVC groups must be previously configured with the application's metadata
0453      * before they can be used. This registration process usually takes place automatically
0454      * at boot time. The type of the group can be normally found in the application's
0455      * configuration file.<p>
0456      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0457      * scenarios <ul>
0458      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0459      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0460      * on any MVC member of the group.</li>
0461      </ul>
0462      <p/>
0463      * For example, with the following entry available in {@code Config.groovy}
0464      <p/>
0465      <pre>
0466      * mvcGroups {
0467      *     foo {
0468      *         model      = 'com.acme.FooModel'
0469      *         view       = 'com.acme.FooView'
0470      *         controller = 'com.acme.FooController'
0471      *     }
0472      *     bar {
0473      *         model      = 'com.acme.FooModel'
0474      *         view       = 'com.acme.BarView'
0475      *         controller = 'com.acme.BarController'
0476      *     }
0477      * }
0478      </pre>
0479      <p/>
0480      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0481      * instance by creating the groups in the following way:
0482      <p/>
0483      <pre>
0484      * FooMVCGroup fooGroup = createMVCGroup(FooMVCGroup)
0485      * BarMVCGroup barGroup = createMVCGroup(BarMVCGroup, model: fooGroup.model)
0486      * assert fooGroup.model == barGroup.model
0487      </pre>
0488      *
0489      @param mvcType the type of group to build.
0490      @param args    any useful values that can be set as properties on each MVC member or that
0491      *                identify a member that can be shared with other groups.
0492      *
0493      @return an MVCGroup instance of the desired type
0494      *
0495      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0496      *                                                           configuration or if a group with the same mvcId exists already.
0497      @since 2.11.0
0498      */
0499     @Nonnull
0500     <MVC extends TypedMVCGroup> MVC createMVCGroup(@Nonnull Class<? extends MVC> mvcType, @Nonnull Map<String, Object> args);
0501 
0502     /**
0503      * Instantiates an MVC group of the specified type with a particular name.<p>
0504      * MVC groups must be previously configured with the application's metadata
0505      * before they can be used. This registration process usually takes place automatically
0506      * at boot time. The type of the group can be normally found in the application's
0507      * configuration file.<p>
0508      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0509      * scenarios <ul>
0510      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0511      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0512      * on any MVC member of the group.</li>
0513      </ul>
0514      <p/>
0515      * For example, with the following entry available in {@code Config.groovy}
0516      <p/>
0517      <pre>
0518      * mvcGroups {
0519      *     foo {
0520      *         model      = 'com.acme.FooModel'
0521      *         view       = 'com.acme.FooView'
0522      *         controller = 'com.acme.FooController'
0523      *     }
0524      * }
0525      </pre>
0526      <p/>
0527      * We can create two instances of the same group that share the same model instance in the following way:
0528      <p/>
0529      <pre>
0530      * FooMVCGroup fooGroup1 = createMVCGroup(FooMVCGroup, 'foo1')
0531      * FooMVCGroup fooGroup2 = createMVCGroup(FooMVCGroup, 'foo2', model: fooGroup1.model)
0532      * assert fooGroup1.model == fooGroup2.model
0533      </pre>
0534      <p/>
0535      * MVC groups must have an unique name.
0536      *
0537      @param args    any useful values that can be set as properties on each MVC member or that
0538      *                identify a member that can be shared with other groups.
0539      @param mvcType the type of group to build.
0540      @param mvcId   the name to assign to the built group.
0541      *
0542      @return an MVCGroup instance of the desired type
0543      *
0544      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0545      *                                                           configuration or if a group with the same mvcId exists already.
0546      @since 2.11.0
0547      */
0548     @Nonnull
0549     <MVC extends TypedMVCGroup> MVC createMVCGroup(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId);
0550 
0551     /**
0552      * Instantiates an MVC group of the specified type with a particular name.<p>
0553      * MVC groups must be previously configured with the application's metadata
0554      * before they can be used. This registration process usually takes place automatically
0555      * at boot time. The type of the group can be normally found in the application's
0556      * configuration file.<p>
0557      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0558      * scenarios <ul>
0559      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0560      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0561      * on any MVC member of the group.</li>
0562      </ul>
0563      <p/>
0564      * For example, with the following entry available in {@code Config.groovy}
0565      <p/>
0566      <pre>
0567      * mvcGroups {
0568      *     foo {
0569      *         model      = 'com.acme.FooModel'
0570      *         view       = 'com.acme.FooView'
0571      *         controller = 'com.acme.FooController'
0572      *     }
0573      * }
0574      </pre>
0575      <p/>
0576      * We can create two instances of the same group that share the same model instance in the following way:
0577      <p/>
0578      <pre>
0579      * FooMVCGroup fooGroup1 = createMVCGroup(FooMVCGroup, 'foo1')
0580      * FooMVCGroup fooGroup2 = createMVCGroup(FooMVCGroup, 'foo2', model: fooGroup1.model)
0581      * assert fooGroup1.model == fooGroup2.model
0582      </pre>
0583      <p/>
0584      * MVC groups must have an unique name.
0585      *
0586      @param mvcType the type of group to build.
0587      @param mvcId   the name to assign to the built group.
0588      @param args    any useful values that can be set as properties on each MVC member or that
0589      *                identify a member that can be shared with other groups.
0590      *
0591      @return an MVCGroup instance of the desired type
0592      *
0593      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0594      *                                                           configuration or if a group with the same mvcId exists already.
0595      @since 2.11.0
0596      */
0597     @Nonnull
0598     <MVC extends TypedMVCGroup> MVC createMVCGroup(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args);
0599 
0600     /**
0601      * Instantiates an MVC group of the specified type returning only the MVC parts.<p>
0602      * MVC groups must be previously configured with the application's metadata
0603      * before they can be used. This registration process usually takes place automatically
0604      * at boot time. The type of the group can be normally found in the application's
0605      * configuration file.<p>
0606      * For example, with the following entry available in {@code Config.groovy}
0607      <p/>
0608      <pre>
0609      * mvcGroups {
0610      *     foo {
0611      *         model      = 'com.acme.FooModel'
0612      *         view       = 'com.acme.FooView'
0613      *         controller = 'com.acme.FooController'
0614      *     }
0615      * }
0616      </pre>
0617      <p/>
0618      * An instance of the "foo" group can be created as follows
0619      <p/>
0620      <pre>
0621      * def (m, v, c) = createMVC('foo')
0622      * assert (c instanceof FooController)
0623      </pre>
0624      *
0625      @param mvcType the type of group to build.
0626      *
0627      @return a List with the canonical MVC members of the group
0628      *
0629      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0630      *                                                           configuration or if a group with the same mvcId exists already.
0631      */
0632     @Nonnull
0633     List<? extends GriffonMvcArtifact> createMVC(@Nonnull String mvcType);
0634 
0635     /**
0636      * Instantiates an MVC group of the specified type with additional variables.<p>
0637      * MVC groups must be previously configured with the application's metadata
0638      * before they can be used. This registration process usually takes place automatically
0639      * at boot time. The type of the group can be normally found in the application's
0640      * configuration file.<p>
0641      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0642      * scenarios <ul>
0643      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0644      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0645      * on any MVC member of the group.</li>
0646      </ul>
0647      <p/>
0648      * For example, with the following entry available in {@code Config.groovy}
0649      <p/>
0650      <pre>
0651      * mvcGroups {
0652      *     foo {
0653      *         model      = 'com.acme.FooModel'
0654      *         view       = 'com.acme.FooView'
0655      *         controller = 'com.acme.FooController'
0656      *     }
0657      *     bar {
0658      *         model      = 'com.acme.FooModel'
0659      *         view       = 'com.acme.BarView'
0660      *         controller = 'com.acme.BarController'
0661      *     }
0662      * }
0663      </pre>
0664      <p/>
0665      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0666      * instance by creating the groups in the following way:
0667      <p/>
0668      <pre>
0669      * def (m1, v1, c1) = createMVC('foo')
0670      * def (m2, v2, c2) = createMVC('bar', model: m1)
0671      * assert fm1 == m2
0672      </pre>
0673      *
0674      @param args    any useful values that can be set as properties on each MVC member or that
0675      *                identify a member that can be shared with other groups.
0676      @param mvcType the type of group to build.
0677      *
0678      @return a List with the canonical MVC members of the group
0679      *
0680      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0681      *                                                           configuration or if a group with the same mvcId exists already.
0682      */
0683     @Nonnull
0684     List<? extends GriffonMvcArtifact> createMVC(@Nonnull Map<String, Object> args, @Nonnull String mvcType);
0685 
0686     /**
0687      * Instantiates an MVC group of the specified type with additional variables.<p>
0688      * MVC groups must be previously configured with the application's metadata
0689      * before they can be used. This registration process usually takes place automatically
0690      * at boot time. The type of the group can be normally found in the application's
0691      * configuration file.<p>
0692      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0693      * scenarios <ul>
0694      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0695      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0696      * on any MVC member of the group.</li>
0697      </ul>
0698      <p/>
0699      * For example, with the following entry available in {@code Config.groovy}
0700      <p/>
0701      <pre>
0702      * mvcGroups {
0703      *     foo {
0704      *         model      = 'com.acme.FooModel'
0705      *         view       = 'com.acme.FooView'
0706      *         controller = 'com.acme.FooController'
0707      *     }
0708      *     bar {
0709      *         model      = 'com.acme.FooModel'
0710      *         view       = 'com.acme.BarView'
0711      *         controller = 'com.acme.BarController'
0712      *     }
0713      * }
0714      </pre>
0715      <p/>
0716      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0717      * instance by creating the groups in the following way:
0718      <p/>
0719      <pre>
0720      * def (m1, v1, c1) = createMVC('foo')
0721      * def (m2, v2, c2) = createMVC('bar', model: m1)
0722      * assert fm1 == m2
0723      </pre>
0724      *
0725      @param mvcType the type of group to build.
0726      @param args    any useful values that can be set as properties on each MVC member or that
0727      *                identify a member that can be shared with other groups.
0728      *
0729      @return a List with the canonical MVC members of the group
0730      *
0731      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0732      *                                                           configuration or if a group with the same mvcId exists already.
0733      */
0734     @Nonnull
0735     List<? extends GriffonMvcArtifact> createMVC(@Nonnull String mvcType, @Nonnull Map<String, Object> args);
0736 
0737     /**
0738      * Instantiates an MVC group of the specified type with a particular name.<p>
0739      * MVC groups must be previously configured with the application's metadata
0740      * before they can be used. This registration process usually takes place automatically
0741      * at boot time. The type of the group can be normally found in the application's
0742      * configuration file.<p>
0743      * For example, with the following entry available in {@code Config.groovy}
0744      <p/>
0745      <pre>
0746      * mvcGroups {
0747      *     foo {
0748      *         model      = 'com.acme.FooModel'
0749      *         view       = 'com.acme.FooView'
0750      *         controller = 'com.acme.FooController'
0751      *      }
0752      * }
0753      </pre>
0754      <p/>
0755      * An instance of the "foo" group can be created as follows
0756      <p/>
0757      <pre>
0758      * def (m, v, c) = createMVC('foo', 'foo' + System.currentTimeMillis())
0759      * assert (c instanceof FooController)
0760      </pre>
0761      <p/>
0762      * MVC groups must have an unique name.
0763      *
0764      @param mvcType the type of group to build.
0765      @param mvcId   the name to assign to the built group.
0766      *
0767      @return a List with the canonical MVC members of the group
0768      *
0769      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0770      *                                                           configuration or if a group with the same mvcId exists already.
0771      */
0772     @Nonnull
0773     List<? extends GriffonMvcArtifact> createMVC(@Nonnull String mvcType, @Nonnull String mvcId);
0774 
0775     /**
0776      * Instantiates an MVC group of the specified type with a particular name.<p>
0777      * MVC groups must be previously configured with the application's metadata
0778      * before they can be used. This registration process usually takes place automatically
0779      * at boot time. The type of the group can be normally found in the application's
0780      * configuration file.<p>
0781      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0782      * scenarios <ul>
0783      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0784      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0785      * on any MVC member of the group.</li>
0786      </ul>
0787      <p/>
0788      * For example, with the following entry available in {@code Config.groovy}
0789      <p/>
0790      <pre>
0791      * mvcGroups {
0792      *     foo {
0793      *         model      = 'com.acme.FooModel'
0794      *         view       = 'com.acme.FooView'
0795      *         controller = 'com.acme.FooController'
0796      *     }
0797      * }
0798      </pre>
0799      <p/>
0800      * We can create two instances of the same group that share the same model instance in the following way:
0801      <p/>
0802      <pre>
0803      * def (m1, v1, c1) = createMVC('foo', 'foo1')
0804      * def (m2, v2, c2) = createMVC('foo', 'foo2', model: m1)
0805      * assert fm1 == m2
0806      </pre>
0807      <p/>
0808      * MVC groups must have an unique name.
0809      *
0810      @param args    any useful values that can be set as properties on each MVC member or that
0811      *                identify a member that can be shared with other groups.
0812      @param mvcType the type of group to build.
0813      @param mvcId   the name to assign to the built group.
0814      *
0815      @return a List with the canonical MVC members of the group
0816      *
0817      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0818      *                                                           configuration or if a group with the same mvcId exists already.
0819      */
0820     @Nonnull
0821     List<? extends GriffonMvcArtifact> createMVC(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull String mvcId);
0822 
0823     /**
0824      * Instantiates an MVC group of the specified type with a particular name.<p>
0825      * MVC groups must be previously configured with the application's metadata
0826      * before they can be used. This registration process usually takes place automatically
0827      * at boot time. The type of the group can be normally found in the application's
0828      * configuration file.<p>
0829      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0830      * scenarios <ul>
0831      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0832      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0833      * on any MVC member of the group.</li>
0834      </ul>
0835      <p/>
0836      * For example, with the following entry available in {@code Config.groovy}
0837      <p/>
0838      <pre>
0839      * mvcGroups {
0840      *     foo {
0841      *         model      = 'com.acme.FooModel'
0842      *         view       = 'com.acme.FooView'
0843      *         controller = 'com.acme.FooController'
0844      *     }
0845      * }
0846      </pre>
0847      <p/>
0848      * We can create two instances of the same group that share the same model instance in the following way:
0849      <p/>
0850      <pre>
0851      * def (m1, v1, c1) = createMVC('foo', 'foo1')
0852      * def (m2, v2, c2) = createMVC('foo', 'foo2', model: m1)
0853      * assert fm1 == m2
0854      </pre>
0855      <p/>
0856      * MVC groups must have an unique name.
0857      *
0858      @param mvcType the type of group to build.
0859      @param mvcId   the name to assign to the built group.
0860      @param args    any useful values that can be set as properties on each MVC member or that
0861      *                identify a member that can be shared with other groups.
0862      *
0863      @return a List with the canonical MVC members of the group
0864      *
0865      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0866      *                                                           configuration or if a group with the same mvcId exists already.
0867      */
0868     @Nonnull
0869     List<? extends GriffonMvcArtifact> createMVC(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args);
0870 
0871     /**
0872      * Instantiates an MVC group of the specified type returning only the MVC parts.<p>
0873      * MVC groups must be previously configured with the application's metadata
0874      * before they can be used. This registration process usually takes place automatically
0875      * at boot time. The type of the group can be normally found in the application's
0876      * configuration file.<p>
0877      * For example, with the following entry available in {@code Config.groovy}
0878      <p/>
0879      <pre>
0880      * mvcGroups {
0881      *     foo {
0882      *         model      = 'com.acme.FooModel'
0883      *         view       = 'com.acme.FooView'
0884      *         controller = 'com.acme.FooController'
0885      *     }
0886      * }
0887      </pre>
0888      <p/>
0889      * An instance of the "foo" group can be created as follows
0890      <p/>
0891      <pre>
0892      * def (m, v, c) = createMVC(FooMVCGroup)
0893      * assert (c instanceof FooController)
0894      </pre>
0895      *
0896      @param mvcType the type of group to build.
0897      *
0898      @return a List with the canonical MVC members of the group
0899      *
0900      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0901      *                                                           configuration or if a group with the same mvcId exists already.
0902      @since 2.11.0
0903      */
0904     @Nonnull
0905     <MVC extends TypedMVCGroup> List<? extends GriffonMvcArtifact> createMVC(@Nonnull Class<? extends MVC> mvcType);
0906 
0907     /**
0908      * Instantiates an MVC group of the specified type with additional variables.<p>
0909      * MVC groups must be previously configured with the application's metadata
0910      * before they can be used. This registration process usually takes place automatically
0911      * at boot time. The type of the group can be normally found in the application's
0912      * configuration file.<p>
0913      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0914      * scenarios <ul>
0915      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0916      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0917      * on any MVC member of the group.</li>
0918      </ul>
0919      <p/>
0920      * For example, with the following entry available in {@code Config.groovy}
0921      <p/>
0922      <pre>
0923      * mvcGroups {
0924      *     foo {
0925      *         model      = 'com.acme.FooModel'
0926      *         view       = 'com.acme.FooView'
0927      *         controller = 'com.acme.FooController'
0928      *     }
0929      *     bar {
0930      *         model      = 'com.acme.FooModel'
0931      *         view       = 'com.acme.BarView'
0932      *         controller = 'com.acme.BarController'
0933      *     }
0934      * }
0935      </pre>
0936      <p/>
0937      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0938      * instance by creating the groups in the following way:
0939      <p/>
0940      <pre>
0941      * def (m1, v1, c1) = createMVC(FooMVCGroup)
0942      * def (m2, v2, c2) = createMVC(BarMVCGroup, model: m1)
0943      * assert fm1 == m2
0944      </pre>
0945      *
0946      @param args    any useful values that can be set as properties on each MVC member or that
0947      *                identify a member that can be shared with other groups.
0948      @param mvcType the type of group to build.
0949      *
0950      @return a List with the canonical MVC members of the group
0951      *
0952      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
0953      *                                                           configuration or if a group with the same mvcId exists already.
0954      @since 2.11.0
0955      */
0956     @Nonnull
0957     <MVC extends TypedMVCGroup> List<? extends GriffonMvcArtifact> createMVC(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType);
0958 
0959     /**
0960      * Instantiates an MVC group of the specified type with additional variables.<p>
0961      * MVC groups must be previously configured with the application's metadata
0962      * before they can be used. This registration process usually takes place automatically
0963      * at boot time. The type of the group can be normally found in the application's
0964      * configuration file.<p>
0965      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0966      * scenarios <ul>
0967      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0968      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0969      * on any MVC member of the group.</li>
0970      </ul>
0971      <p/>
0972      * For example, with the following entry available in {@code Config.groovy}
0973      <p/>
0974      <pre>
0975      * mvcGroups {
0976      *     foo {
0977      *         model      = 'com.acme.FooModel'
0978      *         view       = 'com.acme.FooView'
0979      *         controller = 'com.acme.FooController'
0980      *     }
0981      *     bar {
0982      *         model      = 'com.acme.FooModel'
0983      *         view       = 'com.acme.BarView'
0984      *         controller = 'com.acme.BarController'
0985      *     }
0986      * }
0987      </pre>
0988      <p/>
0989      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0990      * instance by creating the groups in the following way:
0991      <p/>
0992      <pre>
0993      * def (m1, v1, c1) = createMVC(FooMVCGroup)
0994      * def (m2, v2, c2) = createMVC(BarMVCGroup, model: m1)
0995      * assert fm1 == m2
0996      </pre>
0997      *
0998      @param mvcType the type of group to build.
0999      @param args    any useful values that can be set as properties on each MVC member or that
1000      *                identify a member that can be shared with other groups.
1001      *
1002      @return a List with the canonical MVC members of the group
1003      *
1004      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1005      *                                                           configuration or if a group with the same mvcId exists already.
1006      @since 2.11.0
1007      */
1008     @Nonnull
1009     <MVC extends TypedMVCGroup> List<? extends GriffonMvcArtifact> createMVC(@Nonnull Class<? extends MVC> mvcType, @Nonnull Map<String, Object> args);
1010 
1011     /**
1012      * Instantiates an MVC group of the specified type with a particular name.<p>
1013      * MVC groups must be previously configured with the application's metadata
1014      * before they can be used. This registration process usually takes place automatically
1015      * at boot time. The type of the group can be normally found in the application's
1016      * configuration file.<p>
1017      * For example, with the following entry available in {@code Config.groovy}
1018      <p/>
1019      <pre>
1020      * mvcGroups {
1021      *     foo {
1022      *         model      = 'com.acme.FooModel'
1023      *         view       = 'com.acme.FooView'
1024      *         controller = 'com.acme.FooController'
1025      *      }
1026      * }
1027      </pre>
1028      <p/>
1029      * An instance of the "foo" group can be created as follows
1030      <p/>
1031      <pre>
1032      * def (m, v, c) = createMVC(FooMVCGroup, 'foo' + System.currentTimeMillis())
1033      * assert (c instanceof FooController)
1034      </pre>
1035      <p/>
1036      * MVC groups must have an unique name.
1037      *
1038      @param mvcType the type of group to build.
1039      @param mvcId   the name to assign to the built group.
1040      *
1041      @return a List with the canonical MVC members of the group
1042      *
1043      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1044      *                                                           configuration or if a group with the same mvcId exists already.
1045      @since 2.11.0
1046      */
1047     @Nonnull
1048     <MVC extends TypedMVCGroup> List<? extends GriffonMvcArtifact> createMVC(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId);
1049 
1050     /**
1051      * Instantiates an MVC group of the specified type with a particular name.<p>
1052      * MVC groups must be previously configured with the application's metadata
1053      * before they can be used. This registration process usually takes place automatically
1054      * at boot time. The type of the group can be normally found in the application's
1055      * configuration file.<p>
1056      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1057      * scenarios <ul>
1058      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1059      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1060      * on any MVC member of the group.</li>
1061      </ul>
1062      <p/>
1063      * For example, with the following entry available in {@code Config.groovy}
1064      <p/>
1065      <pre>
1066      * mvcGroups {
1067      *     foo {
1068      *         model      = 'com.acme.FooModel'
1069      *         view       = 'com.acme.FooView'
1070      *         controller = 'com.acme.FooController'
1071      *     }
1072      * }
1073      </pre>
1074      <p/>
1075      * We can create two instances of the same group that share the same model instance in the following way:
1076      <p/>
1077      <pre>
1078      * def (m1, v1, c1) = createMVC(FooMVCGroup, 'foo1')
1079      * def (m2, v2, c2) = createMVC(FooMVCGroup, 'foo2', model: m1)
1080      * assert fm1 == m2
1081      </pre>
1082      <p/>
1083      * MVC groups must have an unique name.
1084      *
1085      @param args    any useful values that can be set as properties on each MVC member or that
1086      *                identify a member that can be shared with other groups.
1087      @param mvcType the type of group to build.
1088      @param mvcId   the name to assign to the built group.
1089      *
1090      @return a List with the canonical MVC members of the group
1091      *
1092      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1093      *                                                           configuration or if a group with the same mvcId exists already.
1094      @since 2.11.0
1095      */
1096     @Nonnull
1097     <MVC extends TypedMVCGroup> List<? extends GriffonMvcArtifact> createMVC(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId);
1098 
1099     /**
1100      * Instantiates an MVC group of the specified type with a particular name.<p>
1101      * MVC groups must be previously configured with the application's metadata
1102      * before they can be used. This registration process usually takes place automatically
1103      * at boot time. The type of the group can be normally found in the application's
1104      * configuration file.<p>
1105      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1106      * scenarios <ul>
1107      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1108      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1109      * on any MVC member of the group.</li>
1110      </ul>
1111      <p/>
1112      * For example, with the following entry available in {@code Config.groovy}
1113      <p/>
1114      <pre>
1115      * mvcGroups {
1116      *     foo {
1117      *         model      = 'com.acme.FooModel'
1118      *         view       = 'com.acme.FooView'
1119      *         controller = 'com.acme.FooController'
1120      *     }
1121      * }
1122      </pre>
1123      <p/>
1124      * We can create two instances of the same group that share the same model instance in the following way:
1125      <p/>
1126      <pre>
1127      * def (m1, v1, c1) = createMVC(FooMVCGroup, 'foo1')
1128      * def (m2, v2, c2) = createMVC(FooMVCGroup, 'foo2', model: m1)
1129      * assert fm1 == m2
1130      </pre>
1131      <p/>
1132      * MVC groups must have an unique name.
1133      *
1134      @param mvcType the type of group to build.
1135      @param mvcId   the name to assign to the built group.
1136      @param args    any useful values that can be set as properties on each MVC member or that
1137      *                identify a member that can be shared with other groups.
1138      *
1139      @return a List with the canonical MVC members of the group
1140      *
1141      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1142      *                                                           configuration or if a group with the same mvcId exists already.
1143      @since 2.11.0
1144      */
1145     @Nonnull
1146     <MVC extends TypedMVCGroup> List<? extends GriffonMvcArtifact> createMVC(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args);
1147 
1148     /**
1149      * Destroys an MVC group identified by a particular name.<p>
1150      <b>ATTENTION:</b> make sure to call the super implementation if you override this method
1151      * otherwise group references will not be kept up to date.
1152      *
1153      @param mvcId the name of the group to destroy and dispose.
1154      */
1155     void destroyMVCGroup(@Nonnull String mvcId);
1156 
1157     /**
1158      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1159      <p>This method is of particular interest when working with short lived MVC groups such as
1160      * those used to build dialogs.<p/>
1161      <p>MVC groups must be previously configured with the application's metadata
1162      * before they can be used. This registration process usually takes place automatically
1163      * at boot time. The type of the group can be normally found in the application's
1164      * configuration file.</p>
1165      * For example, with the following entry available in {@code Config.groovy}
1166      <p/>
1167      <pre>
1168      * mvcGroups {
1169      *     foo {
1170      *         model      = 'com.acme.FooModel'
1171      *         view       = 'com.acme.FooView'
1172      *         controller = 'com.acme.FooController'
1173      *    }
1174      * }
1175      </pre>
1176      <p/>
1177      * An instance of the "foo" group can be used as follows
1178      <p/>
1179      <pre>
1180      * withMVC("foo", new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1181      *     public void call(FooModel m, FooView v, FooController c) {
1182      *         m.setSomeProperty(someValue);
1183      *         c.invokeAnAction();
1184      *     }
1185      * });
1186      </pre>
1187      *
1188      @param mvcType the type of group to build.
1189      @param handler a code block used to configure and manage the instantiated group
1190      *
1191      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1192      *                                                           configuration
1193      */
1194     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull String mvcType, @Nonnull MVCFunction<M, V, C> handler);
1195 
1196     /**
1197      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1198      <p>This method is of particular interest when working with short lived MVC groups such as
1199      * those used to build dialogs.<p/>
1200      <p>MVC groups must be previously configured with the application's metadata
1201      * before they can be used. This registration process usually takes place automatically
1202      * at boot time. The type of the group can be normally found in the application's
1203      * configuration file.</p>
1204      * For example, with the following entry available in {@code Config.groovy}
1205      <p/>
1206      <pre>
1207      * mvcGroups {
1208      *     foo {
1209      *         model      = 'com.acme.FooModel'
1210      *         view       = 'com.acme.FooView'
1211      *         controller = 'com.acme.FooController'
1212      *     }
1213      * }
1214      </pre>
1215      <p/>
1216      * An instance of the "foo" group can be used as follows
1217      <p/>
1218      <pre>
1219      * withMVC("foo", "foo1", new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1220      *     public void call(FooModel m, FooView v, FooController c) {
1221      *         m.setSomeProperty(someValue);
1222      *         c.invokeAnAction();
1223      *     }
1224      * });
1225      </pre>
1226      <p/>
1227      * MVC groups must have an unique name.
1228      *
1229      @param mvcType the type of group to build.
1230      @param mvcId   the name to assign to the built group.
1231      @param handler a code block used to configure and manage the instantiated group
1232      *
1233      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1234      *                                                           configuration
1235      */
1236     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull MVCFunction<M, V, C> handler);
1237 
1238     /**
1239      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1240      <p>This method is of particular interest when working with short lived MVC groups such as
1241      * those used to build dialogs.<p/>
1242      <p>MVC groups must be previously configured with the application's metadata
1243      * before they can be used. This registration process usually takes place automatically
1244      * at boot time. The type of the group can be normally found in the application's
1245      * configuration file.</p>
1246      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1247      * scenarios <ul>
1248      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1249      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1250      * on any MVC member of the group.</li>
1251      * For example, with the following entry available in {@code Config.groovy}
1252      <p/>
1253      <pre>
1254      * mvcGroups {
1255      *     foo {
1256      *         model      = 'com.acme.FooModel'
1257      *         view       = 'com.acme.FooView'
1258      *         controller = 'com.acme.FooController'
1259      *     }
1260      * }
1261      </pre>
1262      <p/>
1263      * An instance of the "foo" group can be used as follows
1264      <p/>
1265      <pre>
1266      * Map<String, Object> map = ... // initialized elsewhere
1267      * withMVC("foo", "foo1", map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1268      *    public void call(FooModel m, FooView v, FooController c) {
1269      *        m.setSomeProperty(someValue);
1270      *        c.invokeAnAction();
1271      *    }
1272      * });
1273      </pre>
1274      <p/>
1275      * MVC groups must have an unique name.
1276      *
1277      @param mvcType the type of group to build.
1278      @param mvcId   the name to assign to the built group.
1279      @param args    any useful values that can be set as properties on each MVC member or that
1280      *                identify a member that can be shared with other groups.
1281      @param handler a code block used to configure and manage the instantiated group
1282      *
1283      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1284      *                                                           configuration
1285      */
1286     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args, @Nonnull MVCFunction<M, V, C> handler);
1287 
1288     /**
1289      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1290      <p>This method is of particular interest when working with short lived MVC groups such as
1291      * those used to build dialogs.<p/>
1292      <p>MVC groups must be previously configured with the application's metadata
1293      * before they can be used. This registration process usually takes place automatically
1294      * at boot time. The type of the group can be normally found in the application's
1295      * configuration file.</p>
1296      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1297      * scenarios <ul>
1298      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1299      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1300      * on any MVC member of the group.</li>
1301      * For example, with the following entry available in {@code Config.groovy}
1302      <p/>
1303      <pre>
1304      * mvcGroups {
1305      *     foo {
1306      *         model      = 'com.acme.FooModel'
1307      *         view       = 'com.acme.FooView'
1308      *         controller = 'com.acme.FooController'
1309      *     }
1310      * }
1311      </pre>
1312      <p/>
1313      * An instance of the "foo" group can be used as follows
1314      <p/>
1315      <pre>
1316      * Map<String, Object> map = ... // initialized elsewhere
1317      * withMVC("foo", "foo1", map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1318      *    public void call(FooModel m, FooView v, FooController c) {
1319      *        m.setSomeProperty(someValue);
1320      *        c.invokeAnAction();
1321      *    }
1322      * });
1323      </pre>
1324      <p/>
1325      * MVC groups must have an unique name.
1326      *
1327      @param args    any useful values that can be set as properties on each MVC member or that
1328      *                identify a member that can be shared with other groups.
1329      @param mvcType the type of group to build.
1330      @param mvcId   the name to assign to the built group.
1331      @param handler a code block used to configure and manage the instantiated group
1332      *
1333      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1334      *                                                           configuration
1335      */
1336     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull String mvcId, @Nonnull MVCFunction<M, V, C> handler);
1337 
1338     /**
1339      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1340      <p>This method is of particular interest when working with short lived MVC groups such as
1341      * those used to build dialogs.<p/>
1342      <p>MVC groups must be previously configured with the application's metadata
1343      * before they can be used. This registration process usually takes place automatically
1344      * at boot time. The type of the group can be normally found in the application's
1345      * configuration file.</p>
1346      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1347      * scenarios <ul>
1348      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1349      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1350      * on any MVC member of the group.</li>
1351      * For example, with the following entry available in {@code Config.groovy}
1352      <p/>
1353      <pre>
1354      * mvcGroups {
1355      *     foo {
1356      *         model      = 'com.acme.FooModel'
1357      *         view       = 'com.acme.FooView'
1358      *         controller = 'com.acme.FooController'
1359      *    }
1360      * }
1361      </pre>
1362      <p/>
1363      * An instance of the "foo" group can be used as follows
1364      <p/>
1365      <pre>
1366      * Map<String, Object> map = ... // initialized elsewhere
1367      * withMVC("foo", map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1368      *    public void call(FooModel m, FooView v, FooController c) {
1369      *        m.setSomeProperty(someValue);
1370      *        c.invokeAnAction();
1371      *    }
1372      * });
1373      </pre>
1374      *
1375      @param mvcType the type of group to build.
1376      @param args    any useful values that can be set as properties on each MVC member or that
1377      *                identify a member that can be shared with other groups.
1378      @param handler a code block used to configure and manage the instantiated group
1379      *
1380      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1381      *                                                           configuration
1382      */
1383     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull String mvcType, @Nonnull Map<String, Object> args, @Nonnull MVCFunction<M, V, C> handler);
1384 
1385     /**
1386      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1387      <p>This method is of particular interest when working with short lived MVC groups such as
1388      * those used to build dialogs.<p/>
1389      <p>MVC groups must be previously configured with the application's metadata
1390      * before they can be used. This registration process usually takes place automatically
1391      * at boot time. The type of the group can be normally found in the application's
1392      * configuration file.</p>
1393      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1394      * scenarios <ul>
1395      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1396      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1397      * on any MVC member of the group.</li>
1398      * For example, with the following entry available in {@code Config.groovy}
1399      <p/>
1400      <pre>
1401      * mvcGroups {
1402      *     foo {
1403      *         model      = 'com.acme.FooModel'
1404      *         view       = 'com.acme.FooView'
1405      *         controller = 'com.acme.FooController'
1406      *    }
1407      * }
1408      </pre>
1409      <p/>
1410      * An instance of the "foo" group can be used as follows
1411      <p/>
1412      <pre>
1413      * Map<String, Object> map = ... // initialized elsewhere
1414      * withMVC("foo", map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1415      *    public void call(FooModel m, FooView v, FooController c) {
1416      *        m.setSomeProperty(someValue);
1417      *        c.invokeAnAction();
1418      *    }
1419      * });
1420      </pre>
1421      *
1422      @param args    any useful values that can be set as properties on each MVC member or that
1423      *                identify a member that can be shared with other groups.
1424      @param mvcType the type of group to build.
1425      @param handler a code block used to configure and manage the instantiated group
1426      *
1427      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1428      *                                                           configuration
1429      */
1430     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull MVCFunction<M, V, C> handler);
1431 
1432     /**
1433      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1434      <p>This method is of particular interest when working with short lived MVC groups such as
1435      * those used to build dialogs.<p/>
1436      <p>MVC groups must be previously configured with the application's metadata
1437      * before they can be used. This registration process usually takes place automatically
1438      * at boot time. The type of the group can be normally found in the application's
1439      * configuration file.</p>
1440      * For example, with the following entry available in {@code Config.groovy}
1441      <p/>
1442      <pre>
1443      * mvcGroups {
1444      *     foo {
1445      *         model      = 'com.acme.FooModel'
1446      *         view       = 'com.acme.FooView'
1447      *         controller = 'com.acme.FooController'
1448      *    }
1449      * }
1450      </pre>
1451      <p/>
1452      * An instance of the "foo" group can be used as follows
1453      <p/>
1454      <pre>
1455      * withMVC(FooMVCGroup.class, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1456      *     public void call(FooModel m, FooView v, FooController c) {
1457      *         m.setSomeProperty(someValue);
1458      *         c.invokeAnAction();
1459      *     }
1460      * });
1461      </pre>
1462      *
1463      @param mvcType the type of group to build.
1464      @param handler a code block used to configure and manage the instantiated group
1465      *
1466      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1467      *                                                           configuration
1468      @since 2.11.0
1469      */
1470     <MVC extends TypedMVCGroup, M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Class<? extends MVC> mvcType, @Nonnull MVCFunction<M, V, C> handler);
1471 
1472     /**
1473      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1474      <p>This method is of particular interest when working with short lived MVC groups such as
1475      * those used to build dialogs.<p/>
1476      <p>MVC groups must be previously configured with the application's metadata
1477      * before they can be used. This registration process usually takes place automatically
1478      * at boot time. The type of the group can be normally found in the application's
1479      * configuration file.</p>
1480      * For example, with the following entry available in {@code Config.groovy}
1481      <p/>
1482      <pre>
1483      * mvcGroups {
1484      *     foo {
1485      *         model      = 'com.acme.FooModel'
1486      *         view       = 'com.acme.FooView'
1487      *         controller = 'com.acme.FooController'
1488      *     }
1489      * }
1490      </pre>
1491      <p/>
1492      * An instance of the "foo" group can be used as follows
1493      <p/>
1494      <pre>
1495      * withMVC(FooMVCGroup.class, "foo1", new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1496      *     public void call(FooModel m, FooView v, FooController c) {
1497      *         m.setSomeProperty(someValue);
1498      *         c.invokeAnAction();
1499      *     }
1500      * });
1501      </pre>
1502      <p/>
1503      * MVC groups must have an unique name.
1504      *
1505      @param mvcType the type of group to build.
1506      @param mvcId   the name to assign to the built group.
1507      @param handler a code block used to configure and manage the instantiated group
1508      *
1509      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1510      *                                                           configuration
1511      @since 2.11.0
1512      */
1513     <MVC extends TypedMVCGroup, M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull MVCFunction<M, V, C> handler);
1514 
1515     /**
1516      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1517      <p>This method is of particular interest when working with short lived MVC groups such as
1518      * those used to build dialogs.<p/>
1519      <p>MVC groups must be previously configured with the application's metadata
1520      * before they can be used. This registration process usually takes place automatically
1521      * at boot time. The type of the group can be normally found in the application's
1522      * configuration file.</p>
1523      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1524      * scenarios <ul>
1525      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1526      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1527      * on any MVC member of the group.</li>
1528      * For example, with the following entry available in {@code Config.groovy}
1529      <p/>
1530      <pre>
1531      * mvcGroups {
1532      *     foo {
1533      *         model      = 'com.acme.FooModel'
1534      *         view       = 'com.acme.FooView'
1535      *         controller = 'com.acme.FooController'
1536      *     }
1537      * }
1538      </pre>
1539      <p/>
1540      * An instance of the "foo" group can be used as follows
1541      <p/>
1542      <pre>
1543      * Map<String, Object> map = ... // initialized elsewhere
1544      * withMVC(FooMVCGroup.class, "foo1", map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1545      *    public void call(FooModel m, FooView v, FooController c) {
1546      *        m.setSomeProperty(someValue);
1547      *        c.invokeAnAction();
1548      *    }
1549      * });
1550      </pre>
1551      <p/>
1552      * MVC groups must have an unique name.
1553      *
1554      @param mvcType the type of group to build.
1555      @param mvcId   the name to assign to the built group.
1556      @param args    any useful values that can be set as properties on each MVC member or that
1557      *                identify a member that can be shared with other groups.
1558      @param handler a code block used to configure and manage the instantiated group
1559      *
1560      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1561      *                                                           configuration
1562      @since 2.11.0
1563      */
1564     <MVC extends TypedMVCGroup, M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args, @Nonnull MVCFunction<M, V, C> handler);
1565 
1566     /**
1567      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1568      <p>This method is of particular interest when working with short lived MVC groups such as
1569      * those used to build dialogs.<p/>
1570      <p>MVC groups must be previously configured with the application's metadata
1571      * before they can be used. This registration process usually takes place automatically
1572      * at boot time. The type of the group can be normally found in the application's
1573      * configuration file.</p>
1574      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1575      * scenarios <ul>
1576      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1577      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1578      * on any MVC member of the group.</li>
1579      * For example, with the following entry available in {@code Config.groovy}
1580      <p/>
1581      <pre>
1582      * mvcGroups {
1583      *     foo {
1584      *         model      = 'com.acme.FooModel'
1585      *         view       = 'com.acme.FooView'
1586      *         controller = 'com.acme.FooController'
1587      *     }
1588      * }
1589      </pre>
1590      <p/>
1591      * An instance of the "foo" group can be used as follows
1592      <p/>
1593      <pre>
1594      * Map<String, Object> map = ... // initialized elsewhere
1595      * withMVC(FooMVCGroup.class, "foo1", map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1596      *    public void call(FooModel m, FooView v, FooController c) {
1597      *        m.setSomeProperty(someValue);
1598      *        c.invokeAnAction();
1599      *    }
1600      * });
1601      </pre>
1602      <p/>
1603      * MVC groups must have an unique name.
1604      *
1605      @param args    any useful values that can be set as properties on each MVC member or that
1606      *                identify a member that can be shared with other groups.
1607      @param mvcType the type of group to build.
1608      @param mvcId   the name to assign to the built group.
1609      @param handler a code block used to configure and manage the instantiated group
1610      *
1611      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1612      *                                                           configuration
1613      @since 2.11.0
1614      */
1615     <MVC extends TypedMVCGroup, M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull MVCFunction<M, V, C> handler);
1616 
1617     /**
1618      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1619      <p>This method is of particular interest when working with short lived MVC groups such as
1620      * those used to build dialogs.<p/>
1621      <p>MVC groups must be previously configured with the application's metadata
1622      * before they can be used. This registration process usually takes place automatically
1623      * at boot time. The type of the group can be normally found in the application's
1624      * configuration file.</p>
1625      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1626      * scenarios <ul>
1627      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1628      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1629      * on any MVC member of the group.</li>
1630      * For example, with the following entry available in {@code Config.groovy}
1631      <p/>
1632      <pre>
1633      * mvcGroups {
1634      *     foo {
1635      *         model      = 'com.acme.FooModel'
1636      *         view       = 'com.acme.FooView'
1637      *         controller = 'com.acme.FooController'
1638      *    }
1639      * }
1640      </pre>
1641      <p/>
1642      * An instance of the "foo" group can be used as follows
1643      <p/>
1644      <pre>
1645      * Map<String, Object> map = ... // initialized elsewhere
1646      * withMVC(FooMVCGroup.class, map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1647      *    public void call(FooModel m, FooView v, FooController c) {
1648      *        m.setSomeProperty(someValue);
1649      *        c.invokeAnAction();
1650      *    }
1651      * });
1652      </pre>
1653      *
1654      @param mvcType the type of group to build.
1655      @param args    any useful values that can be set as properties on each MVC member or that
1656      *                identify a member that can be shared with other groups.
1657      @param handler a code block used to configure and manage the instantiated group
1658      *
1659      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1660      *                                                           configuration
1661      @since 2.11.0
1662      */
1663     <MVC extends TypedMVCGroup, M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Class<? extends MVC> mvcType, @Nonnull Map<String, Object> args, @Nonnull MVCFunction<M, V, C> handler);
1664 
1665     /**
1666      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1667      <p>This method is of particular interest when working with short lived MVC groups such as
1668      * those used to build dialogs.<p/>
1669      <p>MVC groups must be previously configured with the application's metadata
1670      * before they can be used. This registration process usually takes place automatically
1671      * at boot time. The type of the group can be normally found in the application's
1672      * configuration file.</p>
1673      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1674      * scenarios <ul>
1675      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1676      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1677      * on any MVC member of the group.</li>
1678      * For example, with the following entry available in {@code Config.groovy}
1679      <p/>
1680      <pre>
1681      * mvcGroups {
1682      *     foo {
1683      *         model      = 'com.acme.FooModel'
1684      *         view       = 'com.acme.FooView'
1685      *         controller = 'com.acme.FooController'
1686      *    }
1687      * }
1688      </pre>
1689      <p/>
1690      * An instance of the "foo" group can be used as follows
1691      <p/>
1692      <pre>
1693      * Map<String, Object> map = ... // initialized elsewhere
1694      * withMVC(FooMVCGroup.class, map, new MVCFunction&lt;FooModel, FooView, FooController&gt;() {
1695      *    public void call(FooModel m, FooView v, FooController c) {
1696      *        m.setSomeProperty(someValue);
1697      *        c.invokeAnAction();
1698      *    }
1699      * });
1700      </pre>
1701      *
1702      @param args    any useful values that can be set as properties on each MVC member or that
1703      *                identify a member that can be shared with other groups.
1704      @param mvcType the type of group to build.
1705      @param handler a code block used to configure and manage the instantiated group
1706      *
1707      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1708      *                                                           configuration
1709      @since 2.11.0
1710      */
1711     <MVC extends TypedMVCGroup, M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVC(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType, @Nonnull MVCFunction<M, V, C> handler);
1712 
1713     /**
1714      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1715      <p>This method is of particular interest when working with short lived MVC groups such as
1716      * those used to build dialogs.<p/>
1717      <p>MVC groups must be previously configured with the application's metadata
1718      * before they can be used. This registration process usually takes place automatically
1719      * at boot time. The type of the group can be normally found in the application's
1720      * configuration file.</p>
1721      * For example, with the following entry available in {@code Config.groovy}
1722      <p/>
1723      <pre>
1724      * mvcGroups {
1725      *     foo {
1726      *         model      = 'com.acme.FooModel'
1727      *         view       = 'com.acme.FooView'
1728      *         controller = 'com.acme.FooController'
1729      *    }
1730      * }
1731      </pre>
1732      <p/>
1733      * An instance of the "foo" group can be used as follows
1734      <p/>
1735      <pre>
1736      * withMVCGroup("foo", new MVCGroupFunction() {
1737      *     public void call(MVCGroup group) {
1738      *         group.getModel().setSomeProperty(someValue);
1739      *         group.getController().invokeAnAction();
1740      *     }
1741      * });
1742      </pre>
1743      *
1744      @param mvcType the type of group to build.
1745      @param handler a code block used to configure and manage the instantiated group
1746      *
1747      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1748      *                                                           configuration
1749      @since 2.1.0
1750      */
1751     void withMVCGroup(@Nonnull String mvcType, @Nonnull MVCGroupFunction handler);
1752 
1753     /**
1754      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1755      <p>This method is of particular interest when working with short lived MVC groups such as
1756      * those used to build dialogs.<p/>
1757      <p>MVC groups must be previously configured with the application's metadata
1758      * before they can be used. This registration process usually takes place automatically
1759      * at boot time. The type of the group can be normally found in the application's
1760      * configuration file.</p>
1761      * For example, with the following entry available in {@code Config.groovy}
1762      <p/>
1763      <pre>
1764      * mvcGroups {
1765      *     foo {
1766      *         model      = 'com.acme.FooModel'
1767      *         view       = 'com.acme.FooView'
1768      *         controller = 'com.acme.FooController'
1769      *     }
1770      * }
1771      </pre>
1772      <p/>
1773      * An instance of the "foo" group can be used as follows
1774      <p/>
1775      <pre>
1776      * withMVCGroup("foo", "foo1", new MVCGroupFunction() {
1777      *     public void call(MVCGroup group) {
1778      *         group.getModel().setSomeProperty(someValue);
1779      *         group.getController().invokeAnAction();
1780      *     }
1781      * });
1782      </pre>
1783      <p/>
1784      * MVC groups must have an unique name.
1785      *
1786      @param mvcType the type of group to build.
1787      @param mvcId   the name to assign to the built group.
1788      @param handler a code block used to configure and manage the instantiated group
1789      *
1790      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1791      *                                                           configuration
1792      @since 2.1.0
1793      */
1794     void withMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull MVCGroupFunction handler);
1795 
1796     /**
1797      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1798      <p>This method is of particular interest when working with short lived MVC groups such as
1799      * those used to build dialogs.<p/>
1800      <p>MVC groups must be previously configured with the application's metadata
1801      * before they can be used. This registration process usually takes place automatically
1802      * at boot time. The type of the group can be normally found in the application's
1803      * configuration file.</p>
1804      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1805      * scenarios <ul>
1806      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1807      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1808      * on any MVC member of the group.</li>
1809      * For example, with the following entry available in {@code Config.groovy}
1810      <p/>
1811      <pre>
1812      * mvcGroups {
1813      *     foo {
1814      *         model      = 'com.acme.FooModel'
1815      *         view       = 'com.acme.FooView'
1816      *         controller = 'com.acme.FooController'
1817      *     }
1818      * }
1819      </pre>
1820      <p/>
1821      * An instance of the "foo" group can be used as follows
1822      <p/>
1823      <pre>
1824      * Map<String, Object> map = ... // initialized elsewhere
1825      * withMVCGroup("foo", "foo1", map, new MVCGroupFunction() {
1826      *    public void call(MVCGroup group) {
1827      *        group.getModel().setSomeProperty(someValue);
1828      *        group.getController().invokeAnAction();
1829      *    }
1830      * });
1831      </pre>
1832      <p/>
1833      * MVC groups must have an unique name.
1834      *
1835      @param mvcType the type of group to build.
1836      @param mvcId   the name to assign to the built group.
1837      @param args    any useful values that can be set as properties on each MVC member or that
1838      *                identify a member that can be shared with other groups.
1839      @param handler a code block used to configure and manage the instantiated group
1840      *
1841      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1842      *                                                           configuration
1843      @since 2.1.0
1844      */
1845     void withMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args, @Nonnull MVCGroupFunction handler);
1846 
1847     /**
1848      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1849      <p>This method is of particular interest when working with short lived MVC groups such as
1850      * those used to build dialogs.<p/>
1851      <p>MVC groups must be previously configured with the application's metadata
1852      * before they can be used. This registration process usually takes place automatically
1853      * at boot time. The type of the group can be normally found in the application's
1854      * configuration file.</p>
1855      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1856      * scenarios <ul>
1857      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1858      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1859      * on any MVC member of the group.</li>
1860      * For example, with the following entry available in {@code Config.groovy}
1861      <p/>
1862      <pre>
1863      * mvcGroups {
1864      *     foo {
1865      *         model      = 'com.acme.FooModel'
1866      *         view       = 'com.acme.FooView'
1867      *         controller = 'com.acme.FooController'
1868      *     }
1869      * }
1870      </pre>
1871      <p/>
1872      * An instance of the "foo" group can be used as follows
1873      <p/>
1874      <pre>
1875      * Map<String, Object> map = ... // initialized elsewhere
1876      * withMVCGroup("foo", "foo1", map, new MVCGroupFunction() {
1877      *    public void call(MVCGroup group) {
1878      *        group.getModel().setSomeProperty(someValue);
1879      *        group.getController().invokeAnAction();
1880      *    }
1881      * });
1882      </pre>
1883      <p/>
1884      * MVC groups must have an unique name.
1885      *
1886      @param args    any useful values that can be set as properties on each MVC member or that
1887      *                identify a member that can be shared with other groups.
1888      @param mvcType the type of group to build.
1889      @param mvcId   the name to assign to the built group.
1890      @param handler a code block used to configure and manage the instantiated group
1891      *
1892      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1893      *                                                           configuration
1894      @since 2.1.0
1895      */
1896     void withMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull String mvcId, @Nonnull MVCGroupFunction handler);
1897 
1898     /**
1899      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1900      <p>This method is of particular interest when working with short lived MVC groups such as
1901      * those used to build dialogs.<p/>
1902      <p>MVC groups must be previously configured with the application's metadata
1903      * before they can be used. This registration process usually takes place automatically
1904      * at boot time. The type of the group can be normally found in the application's
1905      * configuration file.</p>
1906      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1907      * scenarios <ul>
1908      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1909      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1910      * on any MVC member of the group.</li>
1911      * For example, with the following entry available in {@code Config.groovy}
1912      <p/>
1913      <pre>
1914      * mvcGroups {
1915      *     foo {
1916      *         model      = 'com.acme.FooModel'
1917      *         view       = 'com.acme.FooView'
1918      *         controller = 'com.acme.FooController'
1919      *    }
1920      * }
1921      </pre>
1922      <p/>
1923      * An instance of the "foo" group can be used as follows
1924      <p/>
1925      <pre>
1926      * Map<String, Object> map = ... // initialized elsewhere
1927      * withMVCGroup("foo", map, new MVCGroupFunction() {
1928      *    public void call(MVCGroup group) {
1929      *        group.getModel().setSomeProperty(someValue);
1930      *        group.getController().invokeAnAction();
1931      *    }
1932      * });
1933      </pre>
1934      *
1935      @param mvcType the type of group to build.
1936      @param args    any useful values that can be set as properties on each MVC member or that
1937      *                identify a member that can be shared with other groups.
1938      @param handler a code block used to configure and manage the instantiated group
1939      *
1940      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1941      *                                                           configuration
1942      @since 2.1.0
1943      */
1944     void withMVCGroup(@Nonnull String mvcType, @Nonnull Map<String, Object> args, @Nonnull MVCGroupFunction handler);
1945 
1946     /**
1947      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1948      <p>This method is of particular interest when working with short lived MVC groups such as
1949      * those used to build dialogs.<p/>
1950      <p>MVC groups must be previously configured with the application's metadata
1951      * before they can be used. This registration process usually takes place automatically
1952      * at boot time. The type of the group can be normally found in the application's
1953      * configuration file.</p>
1954      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1955      * scenarios <ul>
1956      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1957      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1958      * on any MVC member of the group.</li>
1959      * For example, with the following entry available in {@code Config.groovy}
1960      <p/>
1961      <pre>
1962      * mvcGroups {
1963      *     foo {
1964      *         model      = 'com.acme.FooModel'
1965      *         view       = 'com.acme.FooView'
1966      *         controller = 'com.acme.FooController'
1967      *    }
1968      * }
1969      </pre>
1970      <p/>
1971      * An instance of the "foo" group can be used as follows
1972      <p/>
1973      <pre>
1974      * Map<String, Object> map = ... // initialized elsewhere
1975      * withMVCGroup("foo", map, new MVCGroupFunction() {
1976      *    public void call(MVCGroup group) {
1977      *        group.getModel().setSomeProperty(someValue);
1978      *        group.getController().invokeAnAction();
1979      *    }
1980      * });
1981      </pre>
1982      *
1983      @param args    any useful values that can be set as properties on each MVC member or that
1984      *                identify a member that can be shared with other groups.
1985      @param mvcType the type of group to build.
1986      @param handler a code block used to configure and manage the instantiated group
1987      *
1988      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
1989      *                                                           configuration
1990      @since 2.1.0
1991      */
1992     void withMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull MVCGroupFunction handler);
1993 
1994     /**
1995      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1996      <p>This method is of particular interest when working with short lived MVC groups such as
1997      * those used to build dialogs.<p/>
1998      <p>MVC groups must be previously configured with the application's metadata
1999      * before they can be used. This registration process usually takes place automatically
2000      * at boot time. The type of the group can be normally found in the application's
2001      * configuration file.</p>
2002      * For example, with the following entry available in {@code Config.groovy}
2003      <p/>
2004      <pre>
2005      * mvcGroups {
2006      *     foo {
2007      *         model      = 'com.acme.FooModel'
2008      *         view       = 'com.acme.FooView'
2009      *         controller = 'com.acme.FooController'
2010      *    }
2011      * }
2012      </pre>
2013      <p/>
2014      * An instance of the "foo" group can be used as follows
2015      <p/>
2016      <pre>
2017      * withMVCGroup(FooMVCGroup.class, new TypedMVCGroupFunction<>() {
2018      *     public void call(MVC group) {
2019      *         group.getModel().setSomeProperty(someValue);
2020      *         group.getController().invokeAnAction();
2021      *     }
2022      * });
2023      </pre>
2024      *
2025      @param mvcType the type of group to build.
2026      @param handler a code block used to configure and manage the instantiated group
2027      *
2028      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
2029      *                                                           configuration
2030      @since 2.11.0
2031      */
2032     <MVC extends TypedMVCGroup> void withMVCGroup(@Nonnull Class<? extends MVC> mvcType, @Nonnull TypedMVCGroupFunction<MVC> handler);
2033 
2034     /**
2035      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
2036      <p>This method is of particular interest when working with short lived MVC groups such as
2037      * those used to build dialogs.<p/>
2038      <p>MVC groups must be previously configured with the application's metadata
2039      * before they can be used. This registration process usually takes place automatically
2040      * at boot time. The type of the group can be normally found in the application's
2041      * configuration file.</p>
2042      * For example, with the following entry available in {@code Config.groovy}
2043      <p/>
2044      <pre>
2045      * mvcGroups {
2046      *     foo {
2047      *         model      = 'com.acme.FooModel'
2048      *         view       = 'com.acme.FooView'
2049      *         controller = 'com.acme.FooController'
2050      *     }
2051      * }
2052      </pre>
2053      <p/>
2054      * An instance of the "foo" group can be used as follows
2055      <p/>
2056      <pre>
2057      * withMVCGroup(FooMVCGroup.class, "foo1", new TypedMVCGroupFunction<>() {
2058      *     public void call(MVC group) {
2059      *         group.getModel().setSomeProperty(someValue);
2060      *         group.getController().invokeAnAction();
2061      *     }
2062      * });
2063      </pre>
2064      <p/>
2065      * MVC groups must have an unique name.
2066      *
2067      @param mvcType the type of group to build.
2068      @param mvcId   the name to assign to the built group.
2069      @param handler a code block used to configure and manage the instantiated group
2070      *
2071      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
2072      *                                                           configuration
2073      @since 2.11.0
2074      */
2075     <MVC extends TypedMVCGroup> void withMVCGroup(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull TypedMVCGroupFunction<MVC> handler);
2076 
2077     /**
2078      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
2079      <p>This method is of particular interest when working with short lived MVC groups such as
2080      * those used to build dialogs.<p/>
2081      <p>MVC groups must be previously configured with the application's metadata
2082      * before they can be used. This registration process usually takes place automatically
2083      * at boot time. The type of the group can be normally found in the application's
2084      * configuration file.</p>
2085      * The <tt>args</tt> Map can contain any value that will be used in one of the following
2086      * scenarios <ul>
2087      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
2088      <li>The key does not match a member definition, the value is assumed to be a property that can be set
2089      * on any MVC member of the group.</li>
2090      * For example, with the following entry available in {@code Config.groovy}
2091      <p/>
2092      <pre>
2093      * mvcGroups {
2094      *     foo {
2095      *         model      = 'com.acme.FooModel'
2096      *         view       = 'com.acme.FooView'
2097      *         controller = 'com.acme.FooController'
2098      *     }
2099      * }
2100      </pre>
2101      <p/>
2102      * An instance of the "foo" group can be used as follows
2103      <p/>
2104      <pre>
2105      * Map<String, Object> map = ... // initialized elsewhere
2106      * withMVCGroup(FooMVCGroup.class, "foo1", map, new TypedMVCGroupFunction<>() {
2107      *    public void call(MVC group) {
2108      *        group.getModel().setSomeProperty(someValue);
2109      *        group.getController().invokeAnAction();
2110      *    }
2111      * });
2112      </pre>
2113      <p/>
2114      * MVC groups must have an unique name.
2115      *
2116      @param mvcType the type of group to build.
2117      @param mvcId   the name to assign to the built group.
2118      @param args    any useful values that can be set as properties on each MVC member or that
2119      *                identify a member that can be shared with other groups.
2120      @param handler a code block used to configure and manage the instantiated group
2121      *
2122      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
2123      *                                                           configuration
2124      @since 2.11.0
2125      */
2126     <MVC extends TypedMVCGroup> void withMVCGroup(@Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args, @Nonnull TypedMVCGroupFunction<MVC> handler);
2127 
2128     /**
2129      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
2130      <p>This method is of particular interest when working with short lived MVC groups such as
2131      * those used to build dialogs.<p/>
2132      <p>MVC groups must be previously configured with the application's metadata
2133      * before they can be used. This registration process usually takes place automatically
2134      * at boot time. The type of the group can be normally found in the application's
2135      * configuration file.</p>
2136      * The <tt>args</tt> Map can contain any value that will be used in one of the following
2137      * scenarios <ul>
2138      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
2139      <li>The key does not match a member definition, the value is assumed to be a property that can be set
2140      * on any MVC member of the group.</li>
2141      * For example, with the following entry available in {@code Config.groovy}
2142      <p/>
2143      <pre>
2144      * mvcGroups {
2145      *     foo {
2146      *         model      = 'com.acme.FooModel'
2147      *         view       = 'com.acme.FooView'
2148      *         controller = 'com.acme.FooController'
2149      *     }
2150      * }
2151      </pre>
2152      <p/>
2153      * An instance of the "foo" group can be used as follows
2154      <p/>
2155      <pre>
2156      * Map<String, Object> map = ... // initialized elsewhere
2157      * withMVCGroup(FooMVCGroup.class, "foo1", map, new TypedMVCGroupFunction<>() {
2158      *    public void call(MVC group) {
2159      *        group.getModel().setSomeProperty(someValue);
2160      *        group.getController().invokeAnAction();
2161      *    }
2162      * });
2163      </pre>
2164      <p/>
2165      * MVC groups must have an unique name.
2166      *
2167      @param args    any useful values that can be set as properties on each MVC member or that
2168      *                identify a member that can be shared with other groups.
2169      @param mvcType the type of group to build.
2170      @param mvcId   the name to assign to the built group.
2171      @param handler a code block used to configure and manage the instantiated group
2172      *
2173      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
2174      *                                                           configuration
2175      @since 2.11.0
2176      */
2177     <MVC extends TypedMVCGroup> void withMVCGroup(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType, @Nonnull String mvcId, @Nonnull TypedMVCGroupFunction<MVC> handler);
2178 
2179     /**
2180      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
2181      <p>This method is of particular interest when working with short lived MVC groups such as
2182      * those used to build dialogs.<p/>
2183      <p>MVC groups must be previously configured with the application's metadata
2184      * before they can be used. This registration process usually takes place automatically
2185      * at boot time. The type of the group can be normally found in the application's
2186      * configuration file.</p>
2187      * The <tt>args</tt> Map can contain any value that will be used in one of the following
2188      * scenarios <ul>
2189      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
2190      <li>The key does not match a member definition, the value is assumed to be a property that can be set
2191      * on any MVC member of the group.</li>
2192      * For example, with the following entry available in {@code Config.groovy}
2193      <p/>
2194      <pre>
2195      * mvcGroups {
2196      *     foo {
2197      *         model      = 'com.acme.FooModel'
2198      *         view       = 'com.acme.FooView'
2199      *         controller = 'com.acme.FooController'
2200      *    }
2201      * }
2202      </pre>
2203      <p/>
2204      * An instance of the "foo" group can be used as follows
2205      <p/>
2206      <pre>
2207      * Map<String, Object> map = ... // initialized elsewhere
2208      * withMVCGroup(FooMVCGroup.class, map, new TypedMVCGroupFunction<>() {
2209      *    public void call(MVC group) {
2210      *        group.getModel().setSomeProperty(someValue);
2211      *        group.getController().invokeAnAction();
2212      *    }
2213      * });
2214      </pre>
2215      *
2216      @param mvcType the type of group to build.
2217      @param args    any useful values that can be set as properties on each MVC member or that
2218      *                identify a member that can be shared with other groups.
2219      @param handler a code block used to configure and manage the instantiated group
2220      *
2221      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
2222      *                                                           configuration
2223      @since 2.11.0
2224      */
2225     <MVC extends TypedMVCGroup> void withMVCGroup(@Nonnull Class<? extends MVC> mvcType, @Nonnull Map<String, Object> args, @Nonnull TypedMVCGroupFunction<MVC> handler);
2226 
2227     /**
2228      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
2229      <p>This method is of particular interest when working with short lived MVC groups such as
2230      * those used to build dialogs.<p/>
2231      <p>MVC groups must be previously configured with the application's metadata
2232      * before they can be used. This registration process usually takes place automatically
2233      * at boot time. The type of the group can be normally found in the application's
2234      * configuration file.</p>
2235      * The <tt>args</tt> Map can contain any value that will be used in one of the following
2236      * scenarios <ul>
2237      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
2238      <li>The key does not match a member definition, the value is assumed to be a property that can be set
2239      * on any MVC member of the group.</li>
2240      * For example, with the following entry available in {@code Config.groovy}
2241      <p/>
2242      <pre>
2243      * mvcGroups {
2244      *     foo {
2245      *         model      = 'com.acme.FooModel'
2246      *         view       = 'com.acme.FooView'
2247      *         controller = 'com.acme.FooController'
2248      *    }
2249      * }
2250      </pre>
2251      <p/>
2252      * An instance of the "foo" group can be used as follows
2253      <p/>
2254      <pre>
2255      * Map<String, Object> map = ... // initialized elsewhere
2256      * withMVCGroup(FooMVCGroup.class, map, new TypedMVCGroupFunction<>() {
2257      *    public void call(MVC group) {
2258      *        group.getModel().setSomeProperty(someValue);
2259      *        group.getController().invokeAnAction();
2260      *    }
2261      * });
2262      </pre>
2263      *
2264      @param args    any useful values that can be set as properties on each MVC member or that
2265      *                identify a member that can be shared with other groups.
2266      @param mvcType the type of group to build.
2267      @param handler a code block used to configure and manage the instantiated group
2268      *
2269      @throws griffon.exceptions.MVCGroupInstantiationException - if the type specified is not found in the application's
2270      *                                                           configuration
2271      @since 2.11.0
2272      */
2273     <MVC extends TypedMVCGroup> void withMVCGroup(@Nonnull Map<String, Object> args, @Nonnull Class<? extends MVC> mvcType, @Nonnull TypedMVCGroupFunction<MVC> handler);
2274 }