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