Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
DialogContextManager |
|
| 1.0;1 |
1 | /* | |
2 | * Licensed to the Apache Software Foundation (ASF) under one or more | |
3 | * contributor license agreements. See the NOTICE file distributed with | |
4 | * this work for additional information regarding copyright ownership. | |
5 | * The ASF licenses this file to you under the Apache License, Version 2.0 | |
6 | * (the "License"); you may not use this file except in compliance with | |
7 | * the License. You may obtain a copy of the License at | |
8 | * | |
9 | * http://www.apache.org/licenses/LICENSE-2.0 | |
10 | * | |
11 | * Unless required by applicable law or agreed to in writing, software | |
12 | * distributed under the License is distributed on an "AS IS" BASIS, | |
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
14 | * See the License for the specific language governing permissions and | |
15 | * limitations under the License. | |
16 | */ | |
17 | ||
18 | package org.apache.shale.dialog; | |
19 | ||
20 | import javax.faces.context.FacesContext; | |
21 | ||
22 | /** | |
23 | * <p>Management functions for the {@link DialogContext} instances related | |
24 | * to a particular user's session.</p> | |
25 | * | |
26 | * <p><strong>IMPLEMENTATION NOTE</strong> - Implementations of this interface | |
27 | * will be stored in session scope, so they should be serializable.</p> | |
28 | * | |
29 | * @since 1.0.4 | |
30 | */ | |
31 | public interface DialogContextManager { | |
32 | ||
33 | ||
34 | /** | |
35 | * <p>Create a new instance of the specified dialog configuration, returning | |
36 | * the newly created instance. This instance must contain an | |
37 | * <code>id</code> value that is guaranteed to be unique among all active | |
38 | * instances for the current user. The instance must also have been stored | |
39 | * as a request scope attribute under key <code>Constants.INSTANCE_BEAN</code>. | |
40 | * The new instance will not be associated with any parent instance.</p> | |
41 | * | |
42 | * @param context FacesContext for the current request | |
43 | * @param name Logical name of the dialog to be created | |
44 | * @return The newly created {@link DialogContext} instance, with no | |
45 | * parent dialog association | |
46 | * | |
47 | * @exception IllegalArgumentException if no dialog definition | |
48 | * can be found for the specified logical name | |
49 | */ | |
50 | public DialogContext create(FacesContext context, String name); | |
51 | ||
52 | ||
53 | /** | |
54 | * <p>Create a new instance of the specified dialog configuration, returning | |
55 | * the newly created instance. This instance must contain an | |
56 | * <code>id</code> value that is guaranteed to be unique among all active | |
57 | * instances for the current user. The instance must also have been stored | |
58 | * as a request scope attribute under key <code>Constants.INSTANCE_BEAN</code>. | |
59 | * The new instance will be associated with the specified parent instance, | |
60 | * which must be managed by this {@link DialogContextManager} and therefore | |
61 | * belong to the same user.</p> | |
62 | * | |
63 | * <p><strong>IMPLEMENTATION NOTE</strong> - Applications should generally | |
64 | * not call this method directly, because it will be awkward to associate | |
65 | * the newly created {@link DialogContext} instance with a different view | |
66 | * instance. Instead, this method is primarily intended to support the | |
67 | * ability to automatically associate the {@link DialogContext} for, say, | |
68 | * a pop-up window with the {@link DialogContext} of the corresponding | |
69 | * main window. This facility is supported automatically by the phase | |
70 | * listener that manages saving and restoring the association of a | |
71 | * {@link DialogContext} and its corresponding JSF view.</p> | |
72 | * | |
73 | * @param context FacesContext for the current request | |
74 | * @param name Logical name of the dialog to be executed | |
75 | * @param parent Parent DialogContext with which the new instance | |
76 | * will be assocated (if any) | |
77 | * @return The newly created "child" {@link DialogContext} instance | |
78 | * | |
79 | * @exception IllegalArgumentException if no dialog definition | |
80 | * can be found for the specified logical name | |
81 | * @exception IllegalStateException if the specified <code>parent</code> | |
82 | * instance is not managed by this {@link DialogContextManager} | |
83 | */ | |
84 | public DialogContext create(FacesContext context, String name, | |
85 | DialogContext parent); | |
86 | ||
87 | ||
88 | /** | |
89 | * <p>Return the {@link DialogContext} instance for the specified identifier | |
90 | * (if any); otherwise, return <code>null</code>.</p> | |
91 | * | |
92 | * @param id Dialog identifier for which to return an instance | |
93 | * @return The {@link DialogContext} instance for this identifier, | |
94 | * may be null | |
95 | */ | |
96 | public DialogContext get(String id); | |
97 | ||
98 | ||
99 | /** | |
100 | * <p>Remove the specified {@link DialogContext} instance from the set of | |
101 | * active instances for the current user.</p> | |
102 | * | |
103 | * @param instance {@link DialogContext} instance to be removed | |
104 | */ | |
105 | public void remove(DialogContext instance); | |
106 | ||
107 | ||
108 | // ------------------------------------------ DialogContextManager Listeners | |
109 | ||
110 | ||
111 | /** | |
112 | * Register given {@link DialogContextManagerListener} for this | |
113 | * {@link DialogContextManager}. Listener cannot be <code>null</code>. | |
114 | * | |
115 | * @param listener The {@link DialogContextManagerListener} instance. | |
116 | */ | |
117 | public void addDialogContextManagerListener(DialogContextManagerListener listener); | |
118 | ||
119 | ||
120 | /** | |
121 | * Return the set of currently registered {@link DialogContextManagerListener}s. | |
122 | */ | |
123 | public DialogContextManagerListener[] getDialogContextManagerListeners(); | |
124 | ||
125 | ||
126 | /** | |
127 | * Remove this previously registered {@link DialogContextManagerListener} | |
128 | * for this {@link DialogContextManager}. The listener will no longer receive | |
129 | * any associated callbacks. | |
130 | * | |
131 | * @param listener The {@link DialogContextManagerListener} instance. | |
132 | */ | |
133 | public void removeDialogContextManagerListener(DialogContextManagerListener listener); | |
134 | ||
135 | ||
136 | } |