001 /*
002 * Copyright 2008-2014 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package griffon.core.mvc;
017
018 import griffon.core.artifact.GriffonController;
019 import griffon.core.artifact.GriffonModel;
020 import griffon.core.artifact.GriffonMvcArtifact;
021 import griffon.core.artifact.GriffonView;
022
023 import javax.annotation.Nonnull;
024 import java.util.List;
025 import java.util.Map;
026
027 /**
028 * Base contract for classes that can manipulate MVC groups.
029 * There are 3 types of methods used for instantiating a group:
030 * <ul>
031 * <ol>{@code buildMVCGroup()} - creates a new group instance returning all members.</ol>
032 * <ol>{@code createMVCGroup()} - creates a new group instance returning only Model, View and Controller members.</ol>
033 * <ol>{@code withMVCGroup()} - creates a new group instance and destroys it immediately after it has been processed by the callback.</ol>
034 * </ul>
035 * <p/>
036 * It's worth mentioning that the value of the {@code mvcId} parameter must be unique otherwise a collision will occur.
037 * When that happens the application will report and exception and terminate. This behavior can be configured to be more
038 * lenient, by defining a configuration flag {@code griffon.mvcid.collision} in {@code Config}. <br/>
039 * Accepted values are
040 * <ul>
041 * <ol>warning - reports the error but allows the application to continue. Destroys the existing group before continuing.</ol>
042 * <ol>exception - reports the error and terminates the application. this is the default behavior.</ol>
043 * </ul>
044 *
045 * @author Andres Almiray
046 * @since 2.0.0
047 */
048 public interface MVCHandler {
049 /**
050 * Instantiates an MVC group of the specified type.<p>
051 * MVC Groups must be previously configured with the application's metadata
052 * before they can be used. This registration process usually takes place automatically
053 * at boot time. The type of the group can be normally found in the application's
054 * configuration file.<p>
055 * For example, with the following entry available in {@code Application.groovy}
056 * <p/>
057 * <pre>
058 * mvcGroups {
059 * 'foo' {
060 * model = 'com.acme.FooModel'
061 * view = 'com.acme.FooView'
062 * controller = 'com.acme.FooController'
063 * }
064 * }
065 * </pre>
066 * <p/>
067 * An instance of the "foo" group can be created as follows
068 * <p/>
069 * <pre>
070 * Map<String, Object> fooGroup = buildMVCGroup('foo')
071 * assert (fooGroup.controller instanceof FooController)
072 * </pre>
073 *
074 * @param mvcType the type of group to build.
075 * @return an MVCGroup instance of the desired type
076 * @throws griffon.exceptions.MVCGroupInstantiationException
077 * - if the type specified is not found in the application's
078 * configuration or if a group with the same mvcId exists already.
079 */
080 @Nonnull
081 MVCGroup buildMVCGroup(@Nonnull String mvcType);
082
083 /**
084 * Instantiates an MVC group of the specified type with a particular name.<p>
085 * MVC Groups must be previously configured with the application's metadata
086 * before they can be used. This registration process usually takes place automatically
087 * at boot time. The type of the group can be normally found in the application's
088 * configuration file.<p>
089 * For example, with the following entry available in {@code Application.groovy}
090 * <p/>
091 * <pre>
092 * mvcGroups {
093 * 'foo' {
094 * model = 'com.acme.FooModel'
095 * view = 'com.acme.FooView'
096 * controller = 'com.acme.FooController'
097 * }
098 * }
099 * </pre>
100 * <p/>
101 * An instance of the "foo" group can be created as follows
102 * <p/>
103 * <pre>
104 * Map<String, Object> fooGroup = buildMVCGroup('foo', 'foo' + System.currentTimeMillis())
105 * assert (fooGroup.controller instanceof FooController)
106 * </pre>
107 * <p/>
108 * MVC groups must have an unique name.
109 *
110 * @param mvcType the type of group to build.
111 * @param mvcId the name to assign to the built group.
112 * @return an MVCGroup instance of the desired type
113 * @throws griffon.exceptions.MVCGroupInstantiationException
114 * - if the type specified is not found in the application's
115 * configuration or if a group with the same mvcId exists already.
116 */
117 @Nonnull
118 MVCGroup buildMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId);
119
120 /**
121 * Instantiates an MVC group of the specified type with additional variables.<p>
122 * MVC Groups must be previously configured with the application's metadata
123 * before they can be used. This registration process usually takes place automatically
124 * at boot time. The type of the group can be normally found in the application's
125 * configuration file.<p>
126 * The <tt>args</tt> Map can contain any value that will be used in one of the following
127 * scenarios <ul>
128 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
129 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
130 * on any MVC member of the group.</li>
131 * </ul>
132 * <p/>
133 * For example, with the following entry available in {@code Application.groovy}
134 * <p/>
135 * <pre>
136 * mvcGroups {
137 * 'foo' {
138 * model = 'com.acme.FooModel'
139 * view = 'com.acme.FooView'
140 * controller = 'com.acme.FooController'
141 * }
142 * 'bar' {
143 * model = 'com.acme.FooModel'
144 * view = 'com.acme.BarView'
145 * controller = 'com.acme.BarController'
146 * }
147 * }
148 * </pre>
149 * <p/>
150 * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
151 * instance by creating the groups in the following way:
152 * <p/>
153 * <pre>
154 * Map<String, Object> fooGroup = buildMVCGroup('foo')
155 * Map<String, Object> barGroup = buildMVCGroup('bar', model: fooGroup.model)
156 * assert fooGroup.model == barGroup.model
157 * </pre>
158 *
159 * @param args any useful values that can be set as properties on each MVC member or that
160 * identify a member that can be shared with other groups.
161 * @param mvcType the type of group to build.
162 * @return an MVCGroup instance of the desired type
163 * @throws griffon.exceptions.MVCGroupInstantiationException
164 * - if the type specified is not found in the application's
165 * configuration or if a group with the same mvcId exists already.
166 */
167 @Nonnull
168 MVCGroup buildMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType);
169
170 /**
171 * Instantiates an MVC group of the specified type with additional variables.<p>
172 * MVC Groups must be previously configured with the application's metadata
173 * before they can be used. This registration process usually takes place automatically
174 * at boot time. The type of the group can be normally found in the application's
175 * configuration file.<p>
176 * The <tt>args</tt> Map can contain any value that will be used in one of the following
177 * scenarios <ul>
178 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
179 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
180 * on any MVC member of the group.</li>
181 * </ul>
182 * <p/>
183 * For example, with the following entry available in {@code Application.groovy}
184 * <p/>
185 * <pre>
186 * mvcGroups {
187 * 'foo' {
188 * model = 'com.acme.FooModel'
189 * view = 'com.acme.FooView'
190 * controller = 'com.acme.FooController'
191 * }
192 * 'bar' {
193 * model = 'com.acme.FooModel'
194 * view = 'com.acme.BarView'
195 * controller = 'com.acme.BarController'
196 * }
197 * }
198 * </pre>
199 * <p/>
200 * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
201 * instance by creating the groups in the following way:
202 * <p/>
203 * <pre>
204 * Map<String, Object> fooGroup = buildMVCGroup('foo')
205 * Map<String, Object> barGroup = buildMVCGroup('bar', model: fooGroup.model)
206 * assert fooGroup.model == barGroup.model
207 * </pre>
208 *
209 * @param mvcType the type of group to build.
210 * @param args any useful values that can be set as properties on each MVC member or that
211 * identify a member that can be shared with other groups.
212 * @return an MVCGroup instance of the desired type
213 * @throws griffon.exceptions.MVCGroupInstantiationException
214 * - if the type specified is not found in the application's
215 * configuration or if a group with the same mvcId exists already.
216 */
217 @Nonnull
218 MVCGroup buildMVCGroup(@Nonnull String mvcType, @Nonnull Map<String, Object> args);
219
220 /**
221 * Instantiates an MVC group of the specified type with a particular name.<p>
222 * MVC Groups must be previously configured with the application's metadata
223 * before they can be used. This registration process usually takes place automatically
224 * at boot time. The type of the group can be normally found in the application's
225 * configuration file.<p>
226 * The <tt>args</tt> Map can contain any value that will be used in one of the following
227 * scenarios <ul>
228 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
229 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
230 * on any MVC member of the group.</li>
231 * </ul>
232 * <p/>
233 * For example, with the following entry available in {@code Application.groovy}
234 * <p/>
235 * <pre>
236 * mvcGroups {
237 * 'foo' {
238 * model = 'com.acme.FooModel'
239 * view = 'com.acme.FooView'
240 * controller = 'com.acme.FooController'
241 * }
242 * }
243 * </pre>
244 * <p/>
245 * We can create two instances of the same group that share the same model instance in the following way:
246 * <p/>
247 * <pre>
248 * Map<String, Object> fooGroup1 = buildMVCGroup('foo', 'foo1')
249 * Map<String, Object> fooGroup2 = buildMVCGroup('bar', 'foo2', model: fooGroup1.model)
250 * assert fooGroup1.model == fooGroup2.model
251 * </pre>
252 * <p/>
253 * MVC groups must have an unique name.
254 *
255 * @param args any useful values that can be set as properties on each MVC member or that
256 * identify a member that can be shared with other groups.
257 * @param mvcType the type of group to build.
258 * @param mvcId the name to assign to the built group.
259 * @return an MVCGroup instance of the desired type
260 * @throws griffon.exceptions.MVCGroupInstantiationException
261 * - if the type specified is not found in the application's
262 * configuration or if a group with the same mvcId exists already.
263 */
264 @Nonnull
265 MVCGroup buildMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull String mvcId);
266
267 /**
268 * Instantiates an MVC group of the specified type with a particular name.<p>
269 * MVC Groups must be previously configured with the application's metadata
270 * before they can be used. This registration process usually takes place automatically
271 * at boot time. The type of the group can be normally found in the application's
272 * configuration file.<p>
273 * The <tt>args</tt> Map can contain any value that will be used in one of the following
274 * scenarios <ul>
275 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
276 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
277 * on any MVC member of the group.</li>
278 * </ul>
279 * <p/>
280 * For example, with the following entry available in {@code Application.groovy}
281 * <p/>
282 * <pre>
283 * mvcGroups {
284 * 'foo' {
285 * model = 'com.acme.FooModel'
286 * view = 'com.acme.FooView'
287 * controller = 'com.acme.FooController'
288 * }
289 * }
290 * </pre>
291 * <p/>
292 * We can create two instances of the same group that share the same model instance in the following way:
293 * <p/>
294 * <pre>
295 * Map<String, Object> fooGroup1 = buildMVCGroup('foo', 'foo1')
296 * Map<String, Object> fooGroup2 = buildMVCGroup('bar', 'foo2', model: fooGroup1.model)
297 * assert fooGroup1.model == fooGroup2.model
298 * </pre>
299 * <p/>
300 * MVC groups must have an unique name.
301 *
302 * @param mvcType the type of group to build.
303 * @param mvcId the name to assign to the built group.
304 * @param args any useful values that can be set as properties on each MVC member or that
305 * identify a member that can be shared with other groups.
306 * @return an MVCGroup instance of the desired type
307 * @throws griffon.exceptions.MVCGroupInstantiationException
308 * - if the type specified is not found in the application's
309 * configuration or if a group with the same mvcId exists already.
310 */
311 @Nonnull
312 MVCGroup buildMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args);
313
314 /**
315 * Instantiates an MVC group of the specified type returning only the MVC parts.<p>
316 * MVC Groups must be previously configured with the application's metadata
317 * before they can be used. This registration process usually takes place automatically
318 * at boot time. The type of the group can be normally found in the application's
319 * configuration file.<p>
320 * For example, with the following entry available in {@code Application.groovy}
321 * <p/>
322 * <pre>
323 * mvcGroups {
324 * 'foo' {
325 * model = 'com.acme.FooModel'
326 * view = 'com.acme.FooView'
327 * controller = 'com.acme.FooController'
328 * }
329 * }
330 * </pre>
331 * <p/>
332 * An instance of the "foo" group can be created as follows
333 * <p/>
334 * <pre>
335 * def (m, v, c) = createMVCGroup('foo')
336 * assert (c instanceof FooController)
337 * </pre>
338 *
339 * @param mvcType the type of group to build.
340 * @return a List with the canonical MVC members of the group
341 * @throws griffon.exceptions.MVCGroupInstantiationException
342 * - if the type specified is not found in the application's
343 * configuration or if a group with the same mvcId exists already.
344 */
345 @Nonnull
346 List<? extends GriffonMvcArtifact> createMVCGroup(@Nonnull String mvcType);
347
348 /**
349 * Instantiates an MVC group of the specified type with additional variables.<p>
350 * MVC Groups must be previously configured with the application's metadata
351 * before they can be used. This registration process usually takes place automatically
352 * at boot time. The type of the group can be normally found in the application's
353 * configuration file.<p>
354 * The <tt>args</tt> Map can contain any value that will be used in one of the following
355 * scenarios <ul>
356 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
357 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
358 * on any MVC member of the group.</li>
359 * </ul>
360 * <p/>
361 * For example, with the following entry available in {@code Application.groovy}
362 * <p/>
363 * <pre>
364 * mvcGroups {
365 * 'foo' {
366 * model = 'com.acme.FooModel'
367 * view = 'com.acme.FooView'
368 * controller = 'com.acme.FooController'
369 * }
370 * 'bar' {
371 * model = 'com.acme.FooModel'
372 * view = 'com.acme.BarView'
373 * controller = 'com.acme.BarController'
374 * }
375 * }
376 * </pre>
377 * <p/>
378 * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
379 * instance by creating the groups in the following way:
380 * <p/>
381 * <pre>
382 * def (m1, v1, c1) = createMVCGroup('foo')
383 * def (m2, v2, c2) = createMVCGroup('bar', model: m1)
384 * assert fm1 == m2
385 * </pre>
386 *
387 * @param args any useful values that can be set as properties on each MVC member or that
388 * identify a member that can be shared with other groups.
389 * @param mvcType the type of group to build.
390 * @return a List with the canonical MVC members of the group
391 * @throws griffon.exceptions.MVCGroupInstantiationException
392 * - if the type specified is not found in the application's
393 * configuration or if a group with the same mvcId exists already.
394 */
395 @Nonnull
396 List<? extends GriffonMvcArtifact> createMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType);
397
398 /**
399 * Instantiates an MVC group of the specified type with additional variables.<p>
400 * MVC Groups must be previously configured with the application's metadata
401 * before they can be used. This registration process usually takes place automatically
402 * at boot time. The type of the group can be normally found in the application's
403 * configuration file.<p>
404 * The <tt>args</tt> Map can contain any value that will be used in one of the following
405 * scenarios <ul>
406 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
407 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
408 * on any MVC member of the group.</li>
409 * </ul>
410 * <p/>
411 * For example, with the following entry available in {@code Application.groovy}
412 * <p/>
413 * <pre>
414 * mvcGroups {
415 * 'foo' {
416 * model = 'com.acme.FooModel'
417 * view = 'com.acme.FooView'
418 * controller = 'com.acme.FooController'
419 * }
420 * 'bar' {
421 * model = 'com.acme.FooModel'
422 * view = 'com.acme.BarView'
423 * controller = 'com.acme.BarController'
424 * }
425 * }
426 * </pre>
427 * <p/>
428 * Notice that groups "foo" and "bar share the same model type, We can make them share the same model
429 * instance by creating the groups in the following way:
430 * <p/>
431 * <pre>
432 * def (m1, v1, c1) = createMVCGroup('foo')
433 * def (m2, v2, c2) = createMVCGroup('bar', model: m1)
434 * assert fm1 == m2
435 * </pre>
436 *
437 * @param mvcType the type of group to build.
438 * @param args any useful values that can be set as properties on each MVC member or that
439 * identify a member that can be shared with other groups.
440 * @return a List with the canonical MVC members of the group
441 * @throws griffon.exceptions.MVCGroupInstantiationException
442 * - if the type specified is not found in the application's
443 * configuration or if a group with the same mvcId exists already.
444 */
445 @Nonnull
446 List<? extends GriffonMvcArtifact> createMVCGroup(@Nonnull String mvcType, @Nonnull Map<String, Object> args);
447
448 /**
449 * Instantiates an MVC group of the specified type with a particular name.<p>
450 * MVC Groups must be previously configured with the application's metadata
451 * before they can be used. This registration process usually takes place automatically
452 * at boot time. The type of the group can be normally found in the application's
453 * configuration file.<p>
454 * For example, with the following entry available in {@code Application.groovy}
455 * <p/>
456 * <pre>
457 * mvcGroups {
458 * 'foo' {
459 * model = 'com.acme.FooModel'
460 * view = 'com.acme.FooView'
461 * controller = 'com.acme.FooController'
462 * }
463 * }
464 * </pre>
465 * <p/>
466 * An instance of the "foo" group can be created as follows
467 * <p/>
468 * <pre>
469 * def (m, v, c) = createMVCGroup('foo', 'foo' + System.currenttimeMillis())
470 * assert (c instanceof FooController)
471 * </pre>
472 * <p/>
473 * MVC groups must have an unique name.
474 *
475 * @param mvcType the type of group to build.
476 * @param mvcId the name to assign to the built group.
477 * @return a List with the canonical MVC members of the group
478 * @throws griffon.exceptions.MVCGroupInstantiationException
479 * - if the type specified is not found in the application's
480 * configuration or if a group with the same mvcId exists already.
481 */
482 @Nonnull
483 List<? extends GriffonMvcArtifact> createMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId);
484
485 /**
486 * Instantiates an MVC group of the specified type with a particular name.<p>
487 * MVC Groups must be previously configured with the application's metadata
488 * before they can be used. This registration process usually takes place automatically
489 * at boot time. The type of the group can be normally found in the application's
490 * configuration file.<p>
491 * The <tt>args</tt> Map can contain any value that will be used in one of the following
492 * scenarios <ul>
493 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
494 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
495 * on any MVC member of the group.</li>
496 * </ul>
497 * <p/>
498 * For example, with the following entry available in {@code Application.groovy}
499 * <p/>
500 * <pre>
501 * mvcGroups {
502 * 'foo' {
503 * model = 'com.acme.FooModel'
504 * view = 'com.acme.FooView'
505 * controller = 'com.acme.FooController'
506 * }
507 * }
508 * </pre>
509 * <p/>
510 * We can create two instances of the same group that share the same model instance in the following way:
511 * <p/>
512 * <pre>
513 * def (m1, v1, c1) = createMVCGroup('foo', 'foo1')
514 * def (m2, v2, c2) = createMVCGroup('foo', 'foo2', model: m1)
515 * assert fm1 == m2
516 * </pre>
517 * <p/>
518 * MVC groups must have an unique name.
519 *
520 * @param args any useful values that can be set as properties on each MVC member or that
521 * identify a member that can be shared with other groups.
522 * @param mvcType the type of group to build.
523 * @param mvcId the name to assign to the built group.
524 * @return a List with the canonical MVC members of the group
525 * @throws griffon.exceptions.MVCGroupInstantiationException
526 * - if the type specified is not found in the application's
527 * configuration or if a group with the same mvcId exists already.
528 */
529 @Nonnull
530 List<? extends GriffonMvcArtifact> createMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull String mvcId);
531
532 /**
533 * Instantiates an MVC group of the specified type with a particular name.<p>
534 * MVC Groups must be previously configured with the application's metadata
535 * before they can be used. This registration process usually takes place automatically
536 * at boot time. The type of the group can be normally found in the application's
537 * configuration file.<p>
538 * The <tt>args</tt> Map can contain any value that will be used in one of the following
539 * scenarios <ul>
540 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
541 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
542 * on any MVC member of the group.</li>
543 * </ul>
544 * <p/>
545 * For example, with the following entry available in {@code Application.groovy}
546 * <p/>
547 * <pre>
548 * mvcGroups {
549 * 'foo' {
550 * model = 'com.acme.FooModel'
551 * view = 'com.acme.FooView'
552 * controller = 'com.acme.FooController'
553 * }
554 * }
555 * </pre>
556 * <p/>
557 * We can create two instances of the same group that share the same model instance in the following way:
558 * <p/>
559 * <pre>
560 * def (m1, v1, c1) = createMVCGroup('foo', 'foo1')
561 * def (m2, v2, c2) = createMVCGroup('foo', 'foo2', model: m1)
562 * assert fm1 == m2
563 * </pre>
564 * <p/>
565 * MVC groups must have an unique name.
566 *
567 * @param mvcType the type of group to build.
568 * @param mvcId the name to assign to the built group.
569 * @param args any useful values that can be set as properties on each MVC member or that
570 * identify a member that can be shared with other groups.
571 * @return a List with the canonical MVC members of the group
572 * @throws griffon.exceptions.MVCGroupInstantiationException
573 * - if the type specified is not found in the application's
574 * configuration or if a group with the same mvcId exists already.
575 */
576 @Nonnull
577 List<? extends GriffonMvcArtifact> createMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args);
578
579 /**
580 * Destroys an MVC group identified by a particular name.<p>
581 * <b>ATTENTION:</b> make sure to call the super implementation if you override this method
582 * otherwise group references will not be kept up to date.
583 *
584 * @param mvcId the name of the group to destroy and dispose.
585 */
586 void destroyMVCGroup(@Nonnull String mvcId);
587
588 /**
589 * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
590 * <p>This method is of particular interest when working with short lived MVC groups such as
591 * those used to build dialogs.<p/>
592 * <p>MVC Groups must be previously configured with the application's metadata
593 * before they can be used. This registration process usually takes place automatically
594 * at boot time. The type of the group can be normally found in the application's
595 * configuration file.</p>
596 * For example, with the following entry available in {@code Application.groovy}
597 * <p/>
598 * <pre>
599 * mvcGroups {
600 * 'foo' {
601 * model = 'com.acme.FooModel'
602 * view = 'com.acme.FooView'
603 * controller = 'com.acme.FooController'
604 * }
605 * }
606 * </pre>
607 * <p/>
608 * An instance of the "foo" group can be used as follows
609 * <p/>
610 * <pre>
611 * withMVCGroup("foo", new MVCCallable<FooModel, FooView, FooController>() {
612 * public void call(FooModel m, FooView v, FooController c) {
613 * m.setSomeProperty(someValue);
614 * c.invokeAnAction();
615 * }
616 * });
617 * </pre>
618 *
619 * @param mvcType the type of group to build.
620 * @param handler a code block used to configure and manage the instantiated group
621 * @throws griffon.exceptions.MVCGroupInstantiationException
622 * - if the type specified is not found in the application's
623 * configuration
624 */
625 <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(@Nonnull String mvcType, @Nonnull MVCCallable<M, V, C> handler);
626
627 /**
628 * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
629 * <p>This method is of particular interest when working with short lived MVC groups such as
630 * those used to build dialogs.<p/>
631 * <p>MVC Groups must be previously configured with the application's metadata
632 * before they can be used. This registration process usually takes place automatically
633 * at boot time. The type of the group can be normally found in the application's
634 * configuration file.</p>
635 * For example, with the following entry available in {@code Application.groovy}
636 * <p/>
637 * <pre>
638 * mvcGroups {
639 * 'foo' {
640 * model = 'com.acme.FooModel'
641 * view = 'com.acme.FooView'
642 * controller = 'com.acme.FooController'
643 * }
644 * }
645 * </pre>
646 * <p/>
647 * An instance of the "foo" group can be used as follows
648 * <p/>
649 * <pre>
650 * withMVCGroup("foo", "foo1", new MVCCallable<FooModel, FooView, FooController>() {
651 * public void call(FooModel m, FooView v, FooController c) {
652 * m.setSomeProperty(someValue);
653 * c.invokeAnAction();
654 * }
655 * });
656 * </pre>
657 * <p/>
658 * MVC groups must have an unique name.
659 *
660 * @param mvcType the type of group to build.
661 * @param mvcId the name to assign to the built group.
662 * @param handler a code block used to configure and manage the instantiated group
663 * @throws griffon.exceptions.MVCGroupInstantiationException
664 * - if the type specified is not found in the application's
665 * configuration
666 */
667 <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull MVCCallable<M, V, C> handler);
668
669 /**
670 * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
671 * <p>This method is of particular interest when working with short lived MVC groups such as
672 * those used to build dialogs.<p/>
673 * <p>MVC Groups must be previously configured with the application's metadata
674 * before they can be used. This registration process usually takes place automatically
675 * at boot time. The type of the group can be normally found in the application's
676 * configuration file.</p>
677 * The <tt>args</tt> Map can contain any value that will be used in one of the following
678 * scenarios <ul>
679 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
680 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
681 * on any MVC member of the group.</li>
682 * For example, with the following entry available in {@code Application.groovy}
683 * <p/>
684 * <pre>
685 * mvcGroups {
686 * 'foo' {
687 * model = 'com.acme.FooModel'
688 * view = 'com.acme.FooView'
689 * controller = 'com.acme.FooController'
690 * }
691 * }
692 * </pre>
693 * <p/>
694 * An instance of the "foo" group can be used as follows
695 * <p/>
696 * <pre>
697 * Map<String, Object> map = ... // initialized elsewhere
698 * withMVCGroup("foo", "foo1", map, new MVCCallable<FooModel, FooView, FooController>() {
699 * public void call(FooModel m, FooView v, FooController c) {
700 * m.setSomeProperty(someValue);
701 * c.invokeAnAction();
702 * }
703 * });
704 * </pre>
705 * <p/>
706 * MVC groups must have an unique name.
707 *
708 * @param mvcType the type of group to build.
709 * @param mvcId the name to assign to the built group.
710 * @param args any useful values that can be set as properties on each MVC member or that
711 * identify a member that can be shared with other groups.
712 * @param handler a code block used to configure and manage the instantiated group
713 * @throws griffon.exceptions.MVCGroupInstantiationException
714 * - if the type specified is not found in the application's
715 * configuration
716 */
717 <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(@Nonnull String mvcType, @Nonnull String mvcId, @Nonnull Map<String, Object> args, @Nonnull MVCCallable<M, V, C> handler);
718
719 /**
720 * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
721 * <p>This method is of particular interest when working with short lived MVC groups such as
722 * those used to build dialogs.<p/>
723 * <p>MVC Groups must be previously configured with the application's metadata
724 * before they can be used. This registration process usually takes place automatically
725 * at boot time. The type of the group can be normally found in the application's
726 * configuration file.</p>
727 * The <tt>args</tt> Map can contain any value that will be used in one of the following
728 * scenarios <ul>
729 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
730 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
731 * on any MVC member of the group.</li>
732 * For example, with the following entry available in {@code Application.groovy}
733 * <p/>
734 * <pre>
735 * mvcGroups {
736 * 'foo' {
737 * model = 'com.acme.FooModel'
738 * view = 'com.acme.FooView'
739 * controller = 'com.acme.FooController'
740 * }
741 * }
742 * </pre>
743 * <p/>
744 * An instance of the "foo" group can be used as follows
745 * <p/>
746 * <pre>
747 * Map<String, Object> map = ... // initialized elsewhere
748 * withMVCGroup("foo", "foo1", map, new MVCCallable<FooModel, FooView, FooController>() {
749 * public void call(FooModel m, FooView v, FooController c) {
750 * m.setSomeProperty(someValue);
751 * c.invokeAnAction();
752 * }
753 * });
754 * </pre>
755 * <p/>
756 * MVC groups must have an unique name.
757 *
758 * @param args any useful values that can be set as properties on each MVC member or that
759 * identify a member that can be shared with other groups.
760 * @param mvcType the type of group to build.
761 * @param mvcId the name to assign to the built group.
762 * @param handler a code block used to configure and manage the instantiated group
763 * @throws griffon.exceptions.MVCGroupInstantiationException
764 * - if the type specified is not found in the application's
765 * configuration
766 */
767 <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull String mvcId, @Nonnull MVCCallable<M, V, C> handler);
768
769 /**
770 * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
771 * <p>This method is of particular interest when working with short lived MVC groups such as
772 * those used to build dialogs.<p/>
773 * <p>MVC Groups must be previously configured with the application's metadata
774 * before they can be used. This registration process usually takes place automatically
775 * at boot time. The type of the group can be normally found in the application's
776 * configuration file.</p>
777 * The <tt>args</tt> Map can contain any value that will be used in one of the following
778 * scenarios <ul>
779 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
780 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
781 * on any MVC member of the group.</li>
782 * For example, with the following entry available in {@code Application.groovy}
783 * <p/>
784 * <pre>
785 * mvcGroups {
786 * 'foo' {
787 * model = 'com.acme.FooModel'
788 * view = 'com.acme.FooView'
789 * controller = 'com.acme.FooController'
790 * }
791 * }
792 * </pre>
793 * <p/>
794 * An instance of the "foo" group can be used as follows
795 * <p/>
796 * <pre>
797 * Map<String, Object> map = ... // initialized elsewhere
798 * withMVCGroup("foo", map, new MVCCallable<FooModel, FooView, FooController>() {
799 * public void call(FooModel m, FooView v, FooController c) {
800 * m.setSomeProperty(someValue);
801 * c.invokeAnAction();
802 * }
803 * });
804 * </pre>
805 *
806 * @param mvcType the type of group to build.
807 * @param args any useful values that can be set as properties on each MVC member or that
808 * identify a member that can be shared with other groups.
809 * @param handler a code block used to configure and manage the instantiated group
810 * @throws griffon.exceptions.MVCGroupInstantiationException
811 * - if the type specified is not found in the application's
812 * configuration
813 */
814 <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(@Nonnull String mvcType, @Nonnull Map<String, Object> args, @Nonnull MVCCallable<M, V, C> handler);
815
816 /**
817 * Instantiates an MVC group of the specified type then destroys it after it has been handled.<p>
818 * <p>This method is of particular interest when working with short lived MVC groups such as
819 * those used to build dialogs.<p/>
820 * <p>MVC Groups must be previously configured with the application's metadata
821 * before they can be used. This registration process usually takes place automatically
822 * at boot time. The type of the group can be normally found in the application's
823 * configuration file.</p>
824 * The <tt>args</tt> Map can contain any value that will be used in one of the following
825 * scenarios <ul>
826 * <li>The key matches a member definition; the value will be used as the instance of such member.</li>
827 * <li>The key does not match a member definition, the value is assumed to be a property that can be set
828 * on any MVC member of the group.</li>
829 * For example, with the following entry available in {@code Application.groovy}
830 * <p/>
831 * <pre>
832 * mvcGroups {
833 * 'foo' {
834 * model = 'com.acme.FooModel'
835 * view = 'com.acme.FooView'
836 * controller = 'com.acme.FooController'
837 * }
838 * }
839 * </pre>
840 * <p/>
841 * An instance of the "foo" group can be used as follows
842 * <p/>
843 * <pre>
844 * Map<String, Object> map = ... // initialized elsewhere
845 * withMVCGroup("foo", map, new MVCCallable<FooModel, FooView, FooController>() {
846 * public void call(FooModel m, FooView v, FooController c) {
847 * m.setSomeProperty(someValue);
848 * c.invokeAnAction();
849 * }
850 * });
851 * </pre>
852 *
853 * @param args any useful values that can be set as properties on each MVC member or that
854 * identify a member that can be shared with other groups.
855 * @param mvcType the type of group to build.
856 * @param handler a code block used to configure and manage the instantiated group
857 * @throws griffon.exceptions.MVCGroupInstantiationException
858 * - if the type specified is not found in the application's
859 * configuration
860 */
861 <M extends GriffonModel, V extends GriffonView, C extends GriffonController> void withMVCGroup(@Nonnull Map<String, Object> args, @Nonnull String mvcType, @Nonnull MVCCallable<M, V, C> handler);
862 }
|