MVCHandler.java
0001 /*
0002  * Copyright 2010-2012 the original author or authors.
0003  *
0004  * Licensed under the Apache License, Version 2.0 (the "License");
0005  * you may not use this file except in compliance with the License.
0006  * You may obtain a copy of the License at
0007  *
0008  *      http://www.apache.org/licenses/LICENSE-2.0
0009  *
0010  * Unless required by applicable law or agreed to in writing, software
0011  * distributed under the License is distributed on an "AS IS" BASIS,
0012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0013  * See the License for the specific language governing permissions and
0014  * limitations under the License.
0015  */
0016 package griffon.core;
0017 
0018 import groovy.lang.Closure;
0019 
0020 import java.util.List;
0021 import java.util.Map;
0022 
0023 /**
0024  * Base contract for classes that can manipulate MVC groups.
0025  * There are 3 types of methods used for instantiating a group:
0026  <ul>
0027  <ol>{@code buildMVCGroup()} - creates a new group instance returning all members.</ol>
0028  <ol>{@code createMVCGroup()} - creates a new group instance returning only Model, View and Controller members.</ol>
0029  <ol>{@code withMVCGroup()} - creates a new group instance and  destroys it immediately after it has been processed by the callback.</ol>
0030  </ul>
0031  <p/>
0032  * It's worth mentioning that the value of the {@code mvcName} parameter must be unique otherwise a collision will occur.
0033  * When that happens the application will report and exception and terminate. This behavior can be configured to be more
0034  * lenient, by defining a configuration flag {@code griffon.mvcid.collision} in {@code Config.groovy}. <br/>
0035  * Accepted values are
0036  <ul>
0037  <ol>warning - reports the error but allows the application to continue. Destroys the existing group before continuing.</ol>
0038  <ol>exception - reports the error and terminates the application. this is the default behavior.</ol>
0039  </ul>
0040  *
0041  @author Andres Almiray
0042  @since 0.9.3
0043  */
0044 public interface MVCHandler {
0045     /**
0046      * Instantiates an MVC group of the specified type.<p>
0047      * MVC Groups must be previously configured with the application's metadata
0048      * before they can be used. This registration process usually takes place automatically
0049      * at boot time. The type of the group can be normally found in the application's
0050      * configuration file.<p>
0051      * For example, with the following entry available in {@code Application.groovy}
0052      <p/>
0053      <pre>
0054      * mvcGroups {
0055      *     'foo' {
0056      *         model      = 'com.acme.FooModel'
0057      *         view       = 'com.acme.FooView'
0058      *         controller = 'com.acme.FooController'
0059      *     }
0060      * }
0061      </pre>
0062      <p/>
0063      * An instance of the "foo" group can be created as follows
0064      <p/>
0065      <pre>
0066      * Map<String, Object> fooGroup = buildMVCGroup('foo')
0067      * assert (fooGroup.controller instanceof FooController)
0068      </pre>
0069      *
0070      @param mvcType the type of group to build.
0071      @return an MVCGroup instance of the desired type
0072      @throws griffon.exceptions.MVCGroupInstantiationException
0073      *          - if the type specified is not found in the application's
0074      *          configuration or if a group with the same mvcName exists already.
0075      */
0076     MVCGroup buildMVCGroup(String mvcType);
0077 
0078     /**
0079      * Instantiates an MVC group of the specified type with a particular name.<p>
0080      * MVC Groups must be previously configured with the application's metadata
0081      * before they can be used. This registration process usually takes place automatically
0082      * at boot time. The type of the group can be normally found in the application's
0083      * configuration file.<p>
0084      * For example, with the following entry available in {@code Application.groovy}
0085      <p/>
0086      <pre>
0087      * mvcGroups {
0088      *     'foo' {
0089      *         model      = 'com.acme.FooModel'
0090      *         view       = 'com.acme.FooView'
0091      *         controller = 'com.acme.FooController'
0092      *     }
0093      * }
0094      </pre>
0095      <p/>
0096      * An instance of the "foo" group can be created as follows
0097      <p/>
0098      <pre>
0099      * Map<String, Object> fooGroup = buildMVCGroup('foo', 'foo' + System.currentTimeMillis())
0100      * assert (fooGroup.controller instanceof FooController)
0101      </pre>
0102      <p/>
0103      * MVC groups must have an unique name.
0104      *
0105      @param mvcType the type of group to build.
0106      @param mvcName the name to assign to the built group.
0107      @return an MVCGroup instance of the desired type
0108      @throws griffon.exceptions.MVCGroupInstantiationException
0109      *          - if the type specified is not found in the application's
0110      *          configuration or if a group with the same mvcName exists already.
0111      */
0112     MVCGroup buildMVCGroup(String mvcType, String mvcName);
0113 
0114     /**
0115      * Instantiates an MVC group of the specified type with additional variables.<p>
0116      * MVC Groups must be previously configured with the application's metadata
0117      * before they can be used. This registration process usually takes place automatically
0118      * at boot time. The type of the group can be normally found in the application's
0119      * configuration file.<p>
0120      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0121      * scenarios <ul>
0122      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0123      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0124      * on any MVC member of the group.</li>
0125      </ul>
0126      <p/>
0127      * For example, with the following entry available in {@code Application.groovy}
0128      <p/>
0129      <pre>
0130      * mvcGroups {
0131      *     'foo' {
0132      *         model      = 'com.acme.FooModel'
0133      *         view       = 'com.acme.FooView'
0134      *         controller = 'com.acme.FooController'
0135      *     }
0136      *     'bar' {
0137      *         model      = 'com.acme.FooModel'
0138      *         view       = 'com.acme.BarView'
0139      *         controller = 'com.acme.BarController'
0140      *     }
0141      * }
0142      </pre>
0143      <p/>
0144      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0145      * instance by creating the groups in the following way:
0146      <p/>
0147      <pre>
0148      * Map<String, Object> fooGroup = buildMVCGroup('foo')
0149      * Map<String, Object> barGroup = buildMVCGroup('bar', model: fooGroup.model)
0150      * assert fooGroup.model == barGroup.model
0151      </pre>
0152      *
0153      @param args    any useful values that can be set as properties on each MVC member or that
0154      *                identify a member that can be shared with other groups.
0155      @param mvcType the type of group to build.
0156      @return an MVCGroup instance of the desired type
0157      @throws griffon.exceptions.MVCGroupInstantiationException
0158      *          - if the type specified is not found in the application's
0159      *          configuration or if a group with the same mvcName exists already.
0160      */
0161     MVCGroup buildMVCGroup(Map<String, Object> args, String mvcType);
0162 
0163     /**
0164      * Instantiates an MVC group of the specified type with additional variables.<p>
0165      * MVC Groups must be previously configured with the application's metadata
0166      * before they can be used. This registration process usually takes place automatically
0167      * at boot time. The type of the group can be normally found in the application's
0168      * configuration file.<p>
0169      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0170      * scenarios <ul>
0171      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0172      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0173      * on any MVC member of the group.</li>
0174      </ul>
0175      <p/>
0176      * For example, with the following entry available in {@code Application.groovy}
0177      <p/>
0178      <pre>
0179      * mvcGroups {
0180      *     'foo' {
0181      *         model      = 'com.acme.FooModel'
0182      *         view       = 'com.acme.FooView'
0183      *         controller = 'com.acme.FooController'
0184      *     }
0185      *     'bar' {
0186      *         model      = 'com.acme.FooModel'
0187      *         view       = 'com.acme.BarView'
0188      *         controller = 'com.acme.BarController'
0189      *     }
0190      * }
0191      </pre>
0192      <p/>
0193      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0194      * instance by creating the groups in the following way:
0195      <p/>
0196      <pre>
0197      * Map<String, Object> fooGroup = buildMVCGroup('foo')
0198      * Map<String, Object> barGroup = buildMVCGroup('bar', model: fooGroup.model)
0199      * assert fooGroup.model == barGroup.model
0200      </pre>
0201      *
0202      @param mvcType the type of group to build.
0203      @param args    any useful values that can be set as properties on each MVC member or that
0204      *                identify a member that can be shared with other groups.
0205      @return an MVCGroup instance of the desired type
0206      @throws griffon.exceptions.MVCGroupInstantiationException
0207      *          - if the type specified is not found in the application's
0208      *          configuration or if a group with the same mvcName exists already.
0209      */
0210     MVCGroup buildMVCGroup(String mvcType, Map<String, Object> args);
0211 
0212     /**
0213      * Instantiates an MVC group of the specified type with a particular name.<p>
0214      * MVC Groups must be previously configured with the application's metadata
0215      * before they can be used. This registration process usually takes place automatically
0216      * at boot time. The type of the group can be normally found in the application's
0217      * configuration file.<p>
0218      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0219      * scenarios <ul>
0220      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0221      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0222      * on any MVC member of the group.</li>
0223      </ul>
0224      <p/>
0225      * For example, with the following entry available in {@code Application.groovy}
0226      <p/>
0227      <pre>
0228      * mvcGroups {
0229      *     'foo' {
0230      *         model      = 'com.acme.FooModel'
0231      *         view       = 'com.acme.FooView'
0232      *         controller = 'com.acme.FooController'
0233      *     }
0234      * }
0235      </pre>
0236      <p/>
0237      * We can create two instances of the same group that share the same model instance in the following way:
0238      <p/>
0239      <pre>
0240      * Map<String, Object> fooGroup1 = buildMVCGroup('foo', 'foo1')
0241      * Map<String, Object> fooGroup2 = buildMVCGroup('bar', 'foo2', model: fooGroup1.model)
0242      * assert fooGroup1.model == fooGroup2.model
0243      </pre>
0244      <p/>
0245      * MVC groups must have an unique name.
0246      *
0247      @param args    any useful values that can be set as properties on each MVC member or that
0248      *                identify a member that can be shared with other groups.
0249      @param mvcType the type of group to build.
0250      @param mvcName the name to assign to the built group.
0251      @return an MVCGroup instance of the desired type
0252      @throws griffon.exceptions.MVCGroupInstantiationException
0253      *          - if the type specified is not found in the application's
0254      *          configuration or if a group with the same mvcName exists already.
0255      */
0256     MVCGroup buildMVCGroup(Map<String, Object> args, String mvcType, String mvcName);
0257 
0258     /**
0259      * Instantiates an MVC group of the specified type with a particular name.<p>
0260      * MVC Groups must be previously configured with the application's metadata
0261      * before they can be used. This registration process usually takes place automatically
0262      * at boot time. The type of the group can be normally found in the application's
0263      * configuration file.<p>
0264      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0265      * scenarios <ul>
0266      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0267      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0268      * on any MVC member of the group.</li>
0269      </ul>
0270      <p/>
0271      * For example, with the following entry available in {@code Application.groovy}
0272      <p/>
0273      <pre>
0274      * mvcGroups {
0275      *     'foo' {
0276      *         model      = 'com.acme.FooModel'
0277      *         view       = 'com.acme.FooView'
0278      *         controller = 'com.acme.FooController'
0279      *     }
0280      * }
0281      </pre>
0282      <p/>
0283      * We can create two instances of the same group that share the same model instance in the following way:
0284      <p/>
0285      <pre>
0286      * Map<String, Object> fooGroup1 = buildMVCGroup('foo', 'foo1')
0287      * Map<String, Object> fooGroup2 = buildMVCGroup('bar', 'foo2', model: fooGroup1.model)
0288      * assert fooGroup1.model == fooGroup2.model
0289      </pre>
0290      <p/>
0291      * MVC groups must have an unique name.
0292      *
0293      @param mvcType the type of group to build.
0294      @param mvcName the name to assign to the built group.
0295      @param args    any useful values that can be set as properties on each MVC member or that
0296      *                identify a member that can be shared with other groups.
0297      @return an MVCGroup instance of the desired type
0298      @throws griffon.exceptions.MVCGroupInstantiationException
0299      *          - if the type specified is not found in the application's
0300      *          configuration or if a group with the same mvcName exists already.
0301      */
0302     MVCGroup buildMVCGroup(String mvcType, String mvcName, Map<String, Object> args);
0303 
0304     /**
0305      * Instantiates an MVC group of the specified type returning only the MVC parts.<p>
0306      * MVC Groups must be previously configured with the application's metadata
0307      * before they can be used. This registration process usually takes place automatically
0308      * at boot time. The type of the group can be normally found in the application's
0309      * configuration file.<p>
0310      * For example, with the following entry available in {@code Application.groovy}
0311      <p/>
0312      <pre>
0313      * mvcGroups {
0314      *     'foo' {
0315      *         model      = 'com.acme.FooModel'
0316      *         view       = 'com.acme.FooView'
0317      *         controller = 'com.acme.FooController'
0318      *     }
0319      * }
0320      </pre>
0321      <p/>
0322      * An instance of the "foo" group can be created as follows
0323      <p/>
0324      <pre>
0325      * def (m, v, c) = createMVCGroup('foo')
0326      * assert (c instanceof FooController)
0327      </pre>
0328      *
0329      @param mvcType the type of group to build.
0330      @return a List with the canonical MVC members of the group
0331      @throws griffon.exceptions.MVCGroupInstantiationException
0332      *          - if the type specified is not found in the application's
0333      *          configuration or if a group with the same mvcName exists already.
0334      */
0335     List<? extends GriffonMvcArtifact> createMVCGroup(String mvcType);
0336 
0337     /**
0338      * Instantiates an MVC group of the specified type with additional variables.<p>
0339      * MVC Groups must be previously configured with the application's metadata
0340      * before they can be used. This registration process usually takes place automatically
0341      * at boot time. The type of the group can be normally found in the application's
0342      * configuration file.<p>
0343      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0344      * scenarios <ul>
0345      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0346      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0347      * on any MVC member of the group.</li>
0348      </ul>
0349      <p/>
0350      * For example, with the following entry available in {@code Application.groovy}
0351      <p/>
0352      <pre>
0353      * mvcGroups {
0354      *     'foo' {
0355      *         model      = 'com.acme.FooModel'
0356      *         view       = 'com.acme.FooView'
0357      *         controller = 'com.acme.FooController'
0358      *     }
0359      *     'bar' {
0360      *         model      = 'com.acme.FooModel'
0361      *         view       = 'com.acme.BarView'
0362      *         controller = 'com.acme.BarController'
0363      *     }
0364      * }
0365      </pre>
0366      <p/>
0367      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0368      * instance by creating the groups in the following way:
0369      <p/>
0370      <pre>
0371      * def (m1, v1, c1) = createMVCGroup('foo')
0372      * def (m2, v2, c2) = createMVCGroup('bar', model: m1)
0373      * assert fm1 == m2
0374      </pre>
0375      *
0376      @param args    any useful values that can be set as properties on each MVC member or that
0377      *                identify a member that can be shared with other groups.
0378      @param mvcType the type of group to build.
0379      @return a List with the canonical MVC members of the group
0380      @throws griffon.exceptions.MVCGroupInstantiationException
0381      *          - if the type specified is not found in the application's
0382      *          configuration or if a group with the same mvcName exists already.
0383      */
0384     List<? extends GriffonMvcArtifact> createMVCGroup(Map<String, Object> args, String mvcType);
0385 
0386     /**
0387      * Instantiates an MVC group of the specified type with additional variables.<p>
0388      * MVC Groups must be previously configured with the application's metadata
0389      * before they can be used. This registration process usually takes place automatically
0390      * at boot time. The type of the group can be normally found in the application's
0391      * configuration file.<p>
0392      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0393      * scenarios <ul>
0394      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0395      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0396      * on any MVC member of the group.</li>
0397      </ul>
0398      <p/>
0399      * For example, with the following entry available in {@code Application.groovy}
0400      <p/>
0401      <pre>
0402      * mvcGroups {
0403      *     'foo' {
0404      *         model      = 'com.acme.FooModel'
0405      *         view       = 'com.acme.FooView'
0406      *         controller = 'com.acme.FooController'
0407      *     }
0408      *     'bar' {
0409      *         model      = 'com.acme.FooModel'
0410      *         view       = 'com.acme.BarView'
0411      *         controller = 'com.acme.BarController'
0412      *     }
0413      * }
0414      </pre>
0415      <p/>
0416      * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
0417      * instance by creating the groups in the following way:
0418      <p/>
0419      <pre>
0420      * def (m1, v1, c1) = createMVCGroup('foo')
0421      * def (m2, v2, c2) = createMVCGroup('bar', model: m1)
0422      * assert fm1 == m2
0423      </pre>
0424      *
0425      @param mvcType the type of group to build.
0426      @param args    any useful values that can be set as properties on each MVC member or that
0427      *                identify a member that can be shared with other groups.
0428      @return a List with the canonical MVC members of the group
0429      @throws griffon.exceptions.MVCGroupInstantiationException
0430      *          - if the type specified is not found in the application's
0431      *          configuration or if a group with the same mvcName exists already.
0432      */
0433     List<? extends GriffonMvcArtifact> createMVCGroup(String mvcType, Map<String, Object> args);
0434 
0435     /**
0436      * Instantiates an MVC group of the specified type with a particular name.<p>
0437      * MVC Groups must be previously configured with the application's metadata
0438      * before they can be used. This registration process usually takes place automatically
0439      * at boot time. The type of the group can be normally found in the application's
0440      * configuration file.<p>
0441      * For example, with the following entry available in {@code Application.groovy}
0442      <p/>
0443      <pre>
0444      * mvcGroups {
0445      *     'foo' {
0446      *         model      = 'com.acme.FooModel'
0447      *         view       = 'com.acme.FooView'
0448      *         controller = 'com.acme.FooController'
0449      *      }
0450      * }
0451      </pre>
0452      <p/>
0453      * An instance of the "foo" group can be created as follows
0454      <p/>
0455      <pre>
0456      * def (m, v, c) = createMVCGroup('foo', 'foo' + System.currenttimeMillis())
0457      * assert (c instanceof FooController)
0458      </pre>
0459      <p/>
0460      * MVC groups must have an unique name.
0461      *
0462      @param mvcType the type of group to build.
0463      @param mvcName the name to assign to the built group.
0464      @return a List with the canonical MVC members of the group
0465      @throws griffon.exceptions.MVCGroupInstantiationException
0466      *          - if the type specified is not found in the application's
0467      *          configuration or if a group with the same mvcName exists already.
0468      */
0469     List<? extends GriffonMvcArtifact> createMVCGroup(String mvcType, String mvcName);
0470 
0471     /**
0472      * Instantiates an MVC group of the specified type with a particular name.<p>
0473      * MVC Groups must be previously configured with the application's metadata
0474      * before they can be used. This registration process usually takes place automatically
0475      * at boot time. The type of the group can be normally found in the application's
0476      * configuration file.<p>
0477      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0478      * scenarios <ul>
0479      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0480      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0481      * on any MVC member of the group.</li>
0482      </ul>
0483      <p/>
0484      * For example, with the following entry available in {@code Application.groovy}
0485      <p/>
0486      <pre>
0487      * mvcGroups {
0488      *     'foo' {
0489      *         model      = 'com.acme.FooModel'
0490      *         view       = 'com.acme.FooView'
0491      *         controller = 'com.acme.FooController'
0492      *     }
0493      * }
0494      </pre>
0495      <p/>
0496      * We can create two instances of the same group that share the same model instance in the following way:
0497      <p/>
0498      <pre>
0499      * def (m1, v1, c1) = createMVCGroup('foo', 'foo1')
0500      * def (m2, v2, c2) = createMVCGroup('foo', 'foo2', model: m1)
0501      * assert fm1 == m2
0502      </pre>
0503      <p/>
0504      * MVC groups must have an unique name.
0505      *
0506      @param args    any useful values that can be set as properties on each MVC member or that
0507      *                identify a member that can be shared with other groups.
0508      @param mvcType the type of group to build.
0509      @param mvcName the name to assign to the built group.
0510      @return a List with the canonical MVC members of the group
0511      @throws griffon.exceptions.MVCGroupInstantiationException
0512      *          - if the type specified is not found in the application's
0513      *          configuration or if a group with the same mvcName exists already.
0514      */
0515     List<? extends GriffonMvcArtifact> createMVCGroup(Map<String, Object> args, String mvcType, String mvcName);
0516 
0517     /**
0518      * Instantiates an MVC group of the specified type with a particular name.<p>
0519      * MVC Groups must be previously configured with the application's metadata
0520      * before they can be used. This registration process usually takes place automatically
0521      * at boot time. The type of the group can be normally found in the application's
0522      * configuration file.<p>
0523      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0524      * scenarios <ul>
0525      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0526      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0527      * on any MVC member of the group.</li>
0528      </ul>
0529      <p/>
0530      * For example, with the following entry available in {@code Application.groovy}
0531      <p/>
0532      <pre>
0533      * mvcGroups {
0534      *     'foo' {
0535      *         model      = 'com.acme.FooModel'
0536      *         view       = 'com.acme.FooView'
0537      *         controller = 'com.acme.FooController'
0538      *     }
0539      * }
0540      </pre>
0541      <p/>
0542      * We can create two instances of the same group that share the same model instance in the following way:
0543      <p/>
0544      <pre>
0545      * def (m1, v1, c1) = createMVCGroup('foo', 'foo1')
0546      * def (m2, v2, c2) = createMVCGroup('foo', 'foo2', model: m1)
0547      * assert fm1 == m2
0548      </pre>
0549      <p/>
0550      * MVC groups must have an unique name.
0551      *
0552      @param mvcType the type of group to build.
0553      @param mvcName the name to assign to the built group.
0554      @param args    any useful values that can be set as properties on each MVC member or that
0555      *                identify a member that can be shared with other groups.
0556      @return a List with the canonical MVC members of the group
0557      @throws griffon.exceptions.MVCGroupInstantiationException
0558      *          - if the type specified is not found in the application's
0559      *          configuration or if a group with the same mvcName exists already.
0560      */
0561     List<? extends GriffonMvcArtifact> createMVCGroup(String mvcType, String mvcName, Map<String, Object> args);
0562 
0563     /**
0564      * Destroys an MVC group identified by a particular name.<p>
0565      <b>ATTENTION:</b> make sure to call the super implementation if you override this method
0566      * otherwise group references will not be kept up to date.
0567      *
0568      @param mvcName the name of the group to destroy and dispose.
0569      */
0570     void destroyMVCGroup(String mvcName);
0571 
0572     /**
0573      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0574      <p>This method is of particular interest when working with short lived MVC groups such as
0575      * those used to build dialogs.<p/>
0576      <p>MVC Groups must be previously configured with the application's metadata
0577      * before they can be used. This registration process usually takes place automatically
0578      * at boot time. The type of the group can be normally found in the application's
0579      * configuration file.</p>
0580      * For example, with the following entry available in {@code Application.groovy}
0581      <p/>
0582      <pre>
0583      * mvcGroups {
0584      *     'foo' {
0585      *         model      = 'com.acme.FooModel'
0586      *         view       = 'com.acme.FooView'
0587      *         controller = 'com.acme.FooController'
0588      *     }
0589      * }
0590      </pre>
0591      <p/>
0592      * An instance of the "foo" group can be used as follows
0593      <p/>
0594      <pre>
0595      * withMVCGroup('foo') { m, v, c->
0596      *     m.someProperty = someValue
0597      *     c.invokeAnAction()
0598      * }
0599      </pre>
0600      *
0601      @param mvcType the type of group to build.
0602      @param handler a code block used to configure and manage the instantiated group
0603      @throws griffon.exceptions.MVCGroupInstantiationException
0604      *          - if the type specified is not found in the application's
0605      *          configuration
0606      @since 0.9.3
0607      */
0608     void withMVCGroup(String mvcType, Closure handler);
0609 
0610     /**
0611      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0612      <p>This method is of particular interest when working with short lived MVC groups such as
0613      * those used to build dialogs.<p/>
0614      <p>MVC Groups must be previously configured with the application's metadata
0615      * before they can be used. This registration process usually takes place automatically
0616      * at boot time. The type of the group can be normally found in the application's
0617      * configuration file.</p>
0618      * For example, with the following entry available in {@code Application.groovy}
0619      <p/>
0620      <pre>
0621      * mvcGroups {
0622      *     'foo' {
0623      *         model      = 'com.acme.FooModel'
0624      *         view       = 'com.acme.FooView'
0625      *         controller = 'com.acme.FooController'
0626      *     }
0627      * }
0628      </pre>
0629      <p/>
0630      * An instance of the "foo" group can be used as follows
0631      <p/>
0632      <pre>
0633      * withMVCGroup('foo', 'foo1') { m, v, c->
0634      *     m.someProperty = someValue
0635      *     c.invokeAnAction()
0636      * }
0637      </pre>
0638      <p/>
0639      * MVC groups must have an unique name.
0640      *
0641      @param mvcType the type of group to build.
0642      @param mvcName the name to assign to the built group.
0643      @param handler a code block used to configure and manage the instantiated group
0644      @throws griffon.exceptions.MVCGroupInstantiationException
0645      *          - if the type specified is not found in the application's
0646      *          configuration
0647      @since 0.9.3
0648      */
0649     void withMVCGroup(String mvcType, String mvcName, Closure handler);
0650 
0651     /**
0652      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0653      <p>This method is of particular interest when working with short lived MVC groups such as
0654      * those used to build dialogs.<p/>
0655      <p>MVC Groups must be previously configured with the application's metadata
0656      * before they can be used. This registration process usually takes place automatically
0657      * at boot time. The type of the group can be normally found in the application's
0658      * configuration file.</p>
0659      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0660      * scenarios <ul>
0661      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0662      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0663      * on any MVC member of the group.</li>
0664      * For example, with the following entry available in {@code Application.groovy}
0665      <p/>
0666      <pre>
0667      * mvcGroups {
0668      *     'foo' {
0669      *         model      = 'com.acme.FooModel'
0670      *         view       = 'com.acme.FooView'
0671      *         controller = 'com.acme.FooController'
0672      *     }
0673      * }
0674      </pre>
0675      <p/>
0676      * An instance of the "foo" group can be used as follows
0677      <p/>
0678      <pre>
0679      * withMVCGroup('foo', 'foo1') { m, v, c->
0680      *     m.someProperty = someValue
0681      *     c.invokeAnAction()
0682      * }
0683      </pre>
0684      <p/>
0685      * MVC groups must have an unique name.
0686      *
0687      @param mvcType the type of group to build.
0688      @param mvcName the name to assign to the built group.
0689      @param args    any useful values that can be set as properties on each MVC member or that
0690      *                identify a member that can be shared with other groups.
0691      @param handler a code block used to configure and manage the instantiated group
0692      @throws griffon.exceptions.MVCGroupInstantiationException
0693      *          - if the type specified is not found in the application's
0694      *          configuration
0695      @since 0.9.3
0696      */
0697     void withMVCGroup(String mvcType, String mvcName, Map<String, Object> args, Closure handler);
0698 
0699     /**
0700      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0701      <p>This method is of particular interest when working with short lived MVC groups such as
0702      * those used to build dialogs.<p/>
0703      <p>MVC Groups must be previously configured with the application's metadata
0704      * before they can be used. This registration process usually takes place automatically
0705      * at boot time. The type of the group can be normally found in the application's
0706      * configuration file.</p>
0707      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0708      * scenarios <ul>
0709      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0710      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0711      * on any MVC member of the group.</li>
0712      * For example, with the following entry available in {@code Application.groovy}
0713      <p/>
0714      <pre>
0715      * mvcGroups {
0716      *     'foo' {
0717      *         model      = 'com.acme.FooModel'
0718      *         view       = 'com.acme.FooView'
0719      *         controller = 'com.acme.FooController'
0720      *     }
0721      * }
0722      </pre>
0723      <p/>
0724      * An instance of the "foo" group can be used as follows
0725      <p/>
0726      <pre>
0727      * withMVCGroup('foo', 'foo1') { m, v, c->
0728      *     m.someProperty = someValue
0729      *     c.invokeAnAction()
0730      * }
0731      </pre>
0732      <p/>
0733      * MVC groups must have an unique name.
0734      *
0735      @param args    any useful values that can be set as properties on each MVC member or that
0736      *                identify a member that can be shared with other groups.
0737      @param mvcType the type of group to build.
0738      @param mvcName the name to assign to the built group.
0739      @param handler a code block used to configure and manage the instantiated group
0740      @throws griffon.exceptions.MVCGroupInstantiationException
0741      *          - if the type specified is not found in the application's
0742      *          configuration
0743      @since 0.9.3
0744      */
0745     void withMVCGroup(Map<String, Object> args, String mvcType, String mvcName, Closure handler);
0746 
0747     /**
0748      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0749      <p>This method is of particular interest when working with short lived MVC groups such as
0750      * those used to build dialogs.<p/>
0751      <p>MVC Groups must be previously configured with the application's metadata
0752      * before they can be used. This registration process usually takes place automatically
0753      * at boot time. The type of the group can be normally found in the application's
0754      * configuration file.</p>
0755      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0756      * scenarios <ul>
0757      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0758      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0759      * on any MVC member of the group.</li>
0760      * For example, with the following entry available in {@code Application.groovy}
0761      <p/>
0762      <pre>
0763      * mvcGroups {
0764      *     'foo' {
0765      *         model      = 'com.acme.FooModel'
0766      *         view       = 'com.acme.FooView'
0767      *         controller = 'com.acme.FooController'
0768      *     }
0769      * }
0770      </pre>
0771      <p/>
0772      * An instance of the "foo" group can be used as follows
0773      <p/>
0774      <pre>
0775      * withMVCGroup('foo', 'foo1') { m, v, c->
0776      *     m.someProperty = someValue
0777      *     c.invokeAnAction()
0778      * }
0779      </pre>
0780      *
0781      @param mvcType the type of group to build.
0782      @param args    any useful values that can be set as properties on each MVC member or that
0783      *                identify a member that can be shared with other groups.
0784      @param handler a code block used to configure and manage the instantiated group
0785      @throws griffon.exceptions.MVCGroupInstantiationException
0786      *          - if the type specified is not found in the application's
0787      *          configuration
0788      @since 0.9.3
0789      */
0790     void withMVCGroup(String mvcType, Map<String, Object> args, Closure handler);
0791 
0792     /**
0793      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0794      <p>This method is of particular interest when working with short lived MVC groups such as
0795      * those used to build dialogs.<p/>
0796      <p>MVC Groups must be previously configured with the application's metadata
0797      * before they can be used. This registration process usually takes place automatically
0798      * at boot time. The type of the group can be normally found in the application's
0799      * configuration file.</p>
0800      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0801      * scenarios <ul>
0802      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0803      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0804      * on any MVC member of the group.</li>
0805      * For example, with the following entry available in {@code Application.groovy}
0806      <p/>
0807      <pre>
0808      * mvcGroups {
0809      *     'foo' {
0810      *         model      = 'com.acme.FooModel'
0811      *         view       = 'com.acme.FooView'
0812      *         controller = 'com.acme.FooController'
0813      *     }
0814      * }
0815      </pre>
0816      <p/>
0817      * An instance of the "foo" group can be used as follows
0818      <p/>
0819      <pre>
0820      * withMVCGroup('foo', 'foo1') { m, v, c->
0821      *     m.someProperty = someValue
0822      *     c.invokeAnAction()
0823      * }
0824      </pre>
0825      *
0826      @param args    any useful values that can be set as properties on each MVC member or that
0827      *                identify a member that can be shared with other groups.
0828      @param mvcType the type of group to build.
0829      @param handler a code block used to configure and manage the instantiated group
0830      @throws griffon.exceptions.MVCGroupInstantiationException
0831      *          - if the type specified is not found in the application's
0832      *          configuration
0833      @since 0.9.3
0834      */
0835     void withMVCGroup(Map<String, Object> args, String mvcType, Closure handler);
0836 
0837     /**
0838      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0839      <p>This method is of particular interest when working with short lived MVC groups such as
0840      * those used to build dialogs.<p/>
0841      <p>MVC Groups must be previously configured with the application's metadata
0842      * before they can be used. This registration process usually takes place automatically
0843      * at boot time. The type of the group can be normally found in the application's
0844      * configuration file.</p>
0845      * For example, with the following entry available in {@code Application.groovy}
0846      <p/>
0847      <pre>
0848      * mvcGroups {
0849      *     'foo' {
0850      *         model      = 'com.acme.FooModel'
0851      *         view       = 'com.acme.FooView'
0852      *         controller = 'com.acme.FooController'
0853      *    }
0854      * }
0855      </pre>
0856      <p/>
0857      * An instance of the "foo" group can be used as follows
0858      <p/>
0859      <pre>
0860      * withMVCGroup("foo", new MVCClosure&lt;FooModel, FooView, FooController&gt;() {
0861      *     public void call(FooModel m, FooView v, FooController c) {
0862      *         m.setSomeProperty(someValue);
0863      *         c.invokeAnAction();
0864      *     }
0865      * });
0866      </pre>
0867      *
0868      @param mvcType the type of group to build.
0869      @param handler a code block used to configure and manage the instantiated group
0870      @throws griffon.exceptions.MVCGroupInstantiationException
0871      *          - if the type specified is not found in the application's
0872      *          configuration
0873      @since 0.9.3
0874      */
0875     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(String mvcType, MVCClosure<M, V, C> handler);
0876 
0877     /**
0878      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0879      <p>This method is of particular interest when working with short lived MVC groups such as
0880      * those used to build dialogs.<p/>
0881      <p>MVC Groups must be previously configured with the application's metadata
0882      * before they can be used. This registration process usually takes place automatically
0883      * at boot time. The type of the group can be normally found in the application's
0884      * configuration file.</p>
0885      * For example, with the following entry available in {@code Application.groovy}
0886      <p/>
0887      <pre>
0888      * mvcGroups {
0889      *     'foo' {
0890      *         model      = 'com.acme.FooModel'
0891      *         view       = 'com.acme.FooView'
0892      *         controller = 'com.acme.FooController'
0893      *     }
0894      * }
0895      </pre>
0896      <p/>
0897      * An instance of the "foo" group can be used as follows
0898      <p/>
0899      <pre>
0900      * withMVCGroup("foo", "foo1", new MVCClosure&lt;FooModel, FooView, FooController&gt;() {
0901      *     public void call(FooModel m, FooView v, FooController c) {
0902      *         m.setSomeProperty(someValue);
0903      *         c.invokeAnAction();
0904      *     }
0905      * });
0906      </pre>
0907      <p/>
0908      * MVC groups must have an unique name.
0909      *
0910      @param mvcType the type of group to build.
0911      @param mvcName the name to assign to the built group.
0912      @param handler a code block used to configure and manage the instantiated group
0913      @throws griffon.exceptions.MVCGroupInstantiationException
0914      *          - if the type specified is not found in the application's
0915      *          configuration
0916      @since 0.9.3
0917      */
0918     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(String mvcType, String mvcName, MVCClosure<M, V, C> handler);
0919 
0920     /**
0921      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0922      <p>This method is of particular interest when working with short lived MVC groups such as
0923      * those used to build dialogs.<p/>
0924      <p>MVC Groups must be previously configured with the application's metadata
0925      * before they can be used. This registration process usually takes place automatically
0926      * at boot time. The type of the group can be normally found in the application's
0927      * configuration file.</p>
0928      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0929      * scenarios <ul>
0930      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0931      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0932      * on any MVC member of the group.</li>
0933      * For example, with the following entry available in {@code Application.groovy}
0934      <p/>
0935      <pre>
0936      * mvcGroups {
0937      *     'foo' {
0938      *         model      = 'com.acme.FooModel'
0939      *         view       = 'com.acme.FooView'
0940      *         controller = 'com.acme.FooController'
0941      *     }
0942      * }
0943      </pre>
0944      <p/>
0945      * An instance of the "foo" group can be used as follows
0946      <p/>
0947      <pre>
0948      * Map<String, Object> map = ... // initialized elsewhere
0949      * withMVCGroup("foo", "foo1", map, new MVCClosure&lt;FooModel, FooView, FooController&gt;() {
0950      *    public void call(FooModel m, FooView v, FooController c) {
0951      *        m.setSomeProperty(someValue);
0952      *        c.invokeAnAction();
0953      *    }
0954      * });
0955      </pre>
0956      <p/>
0957      * MVC groups must have an unique name.
0958      *
0959      @param mvcType the type of group to build.
0960      @param mvcName the name to assign to the built group.
0961      @param args    any useful values that can be set as properties on each MVC member or that
0962      *                identify a member that can be shared with other groups.
0963      @param handler a code block used to configure and manage the instantiated group
0964      @throws griffon.exceptions.MVCGroupInstantiationException
0965      *          - if the type specified is not found in the application's
0966      *          configuration
0967      @since 0.9.3
0968      */
0969     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(String mvcType, String mvcName, Map<String, Object> args, MVCClosure<M, V, C> handler);
0970 
0971     /**
0972      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
0973      <p>This method is of particular interest when working with short lived MVC groups such as
0974      * those used to build dialogs.<p/>
0975      <p>MVC Groups must be previously configured with the application's metadata
0976      * before they can be used. This registration process usually takes place automatically
0977      * at boot time. The type of the group can be normally found in the application's
0978      * configuration file.</p>
0979      * The <tt>args</tt> Map can contain any value that will be used in one of the following
0980      * scenarios <ul>
0981      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
0982      <li>The key does not match a member definition, the value is assumed to be a property that can be set
0983      * on any MVC member of the group.</li>
0984      * For example, with the following entry available in {@code Application.groovy}
0985      <p/>
0986      <pre>
0987      * mvcGroups {
0988      *     'foo' {
0989      *         model      = 'com.acme.FooModel'
0990      *         view       = 'com.acme.FooView'
0991      *         controller = 'com.acme.FooController'
0992      *     }
0993      * }
0994      </pre>
0995      <p/>
0996      * An instance of the "foo" group can be used as follows
0997      <p/>
0998      <pre>
0999      * Map<String, Object> map = ... // initialized elsewhere
1000      * withMVCGroup("foo", "foo1", map, new MVCClosure&lt;FooModel, FooView, FooController&gt;() {
1001      *    public void call(FooModel m, FooView v, FooController c) {
1002      *        m.setSomeProperty(someValue);
1003      *        c.invokeAnAction();
1004      *    }
1005      * });
1006      </pre>
1007      <p/>
1008      * MVC groups must have an unique name.
1009      *
1010      @param args    any useful values that can be set as properties on each MVC member or that
1011      *                identify a member that can be shared with other groups.
1012      @param mvcType the type of group to build.
1013      @param mvcName the name to assign to the built group.
1014      @param handler a code block used to configure and manage the instantiated group
1015      @throws griffon.exceptions.MVCGroupInstantiationException
1016      *          - if the type specified is not found in the application's
1017      *          configuration
1018      @since 0.9.3
1019      */
1020     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(Map<String, Object> args, String mvcType, String mvcName, MVCClosure<M, V, C> handler);
1021 
1022     /**
1023      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1024      <p>This method is of particular interest when working with short lived MVC groups such as
1025      * those used to build dialogs.<p/>
1026      <p>MVC Groups must be previously configured with the application's metadata
1027      * before they can be used. This registration process usually takes place automatically
1028      * at boot time. The type of the group can be normally found in the application's
1029      * configuration file.</p>
1030      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1031      * scenarios <ul>
1032      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1033      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1034      * on any MVC member of the group.</li>
1035      * For example, with the following entry available in {@code Application.groovy}
1036      <p/>
1037      <pre>
1038      * mvcGroups {
1039      *     'foo' {
1040      *         model      = 'com.acme.FooModel'
1041      *         view       = 'com.acme.FooView'
1042      *         controller = 'com.acme.FooController'
1043      *    }
1044      * }
1045      </pre>
1046      <p/>
1047      * An instance of the "foo" group can be used as follows
1048      <p/>
1049      <pre>
1050      * Map<String, Object> map = ... // initialized elsewhere
1051      * withMVCGroup("foo", map, new MVCClosure&lt;FooModel, FooView, FooController&gt;() {
1052      *    public void call(FooModel m, FooView v, FooController c) {
1053      *        m.setSomeProperty(someValue);
1054      *        c.invokeAnAction();
1055      *    }
1056      * });
1057      </pre>
1058      *
1059      @param mvcType the type of group to build.
1060      @param args    any useful values that can be set as properties on each MVC member or that
1061      *                identify a member that can be shared with other groups.
1062      @param handler a code block used to configure and manage the instantiated group
1063      @throws griffon.exceptions.MVCGroupInstantiationException
1064      *          - if the type specified is not found in the application's
1065      *          configuration
1066      @since 0.9.3
1067      */
1068     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(String mvcType, Map<String, Object> args, MVCClosure<M, V, C> handler);
1069 
1070     /**
1071      * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
1072      <p>This method is of particular interest when working with short lived MVC groups such as
1073      * those used to build dialogs.<p/>
1074      <p>MVC Groups must be previously configured with the application's metadata
1075      * before they can be used. This registration process usually takes place automatically
1076      * at boot time. The type of the group can be normally found in the application's
1077      * configuration file.</p>
1078      * The <tt>args</tt> Map can contain any value that will be used in one of the following
1079      * scenarios <ul>
1080      <li>The key matches a member definition; the value will be used as the instance of such member.</li>
1081      <li>The key does not match a member definition, the value is assumed to be a property that can be set
1082      * on any MVC member of the group.</li>
1083      * For example, with the following entry available in {@code Application.groovy}
1084      <p/>
1085      <pre>
1086      * mvcGroups {
1087      *     'foo' {
1088      *         model      = 'com.acme.FooModel'
1089      *         view       = 'com.acme.FooView'
1090      *         controller = 'com.acme.FooController'
1091      *    }
1092      * }
1093      </pre>
1094      <p/>
1095      * An instance of the "foo" group can be used as follows
1096      <p/>
1097      <pre>
1098      * Map<String, Object> map = ... // initialized elsewhere
1099      * withMVCGroup("foo", map, new MVCClosure&lt;FooModel, FooView, FooController&gt;() {
1100      *    public void call(FooModel m, FooView v, FooController c) {
1101      *        m.setSomeProperty(someValue);
1102      *        c.invokeAnAction();
1103      *    }
1104      * });
1105      </pre>
1106      *
1107      @param args    any useful values that can be set as properties on each MVC member or that
1108      *                identify a member that can be shared with other groups.
1109      @param mvcType the type of group to build.
1110      @param handler a code block used to configure and manage the instantiated group
1111      @throws griffon.exceptions.MVCGroupInstantiationException
1112      *          - if the type specified is not found in the application's
1113      *          configuration
1114      @since 0.9.3
1115      */
1116     <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(Map<String, Object> args, String mvcType, MVCClosure<M, V, C> handler);
1117 }