2009/05/20 - Apache Shale has been retired.

For more information, please explore the Attic.


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>Return the currently active {@link DialogContext} instance for the
101      * current request, if there is one; otherwise, return <code>null</code>.</p>
102      *
103      * @param context <code>FacesContext</code> for the current request
104      *
105      * @since 1.1.0
106      */
107     public DialogContext getActiveDialogContext(FacesContext context);
108 
109 
110     /***
111      * <p>Remove the specified {@link DialogContext} instance from the set of
112      * active instances for the current user.</p>
113      *
114      * @param instance {@link DialogContext} instance to be removed
115      */
116     public void remove(DialogContext instance);
117 
118 
119     // ------------------------------------------ DialogContextManager Listeners
120 
121 
122     /***
123      * Register given {@link DialogContextManagerListener} for this
124      * {@link DialogContextManager}.  Listener cannot be <code>null</code>.
125      *
126      * @param listener The {@link DialogContextManagerListener} instance.
127      */
128     public void addDialogContextManagerListener(DialogContextManagerListener listener);
129 
130 
131     /***
132      * Return the set of currently registered {@link DialogContextManagerListener}s.
133      */
134     public DialogContextManagerListener[] getDialogContextManagerListeners();
135 
136 
137     /***
138      * Remove this previously registered {@link DialogContextManagerListener}
139      * for this {@link DialogContextManager}. The listener will no longer receive
140      * any associated callbacks.
141      *
142      * @param listener The {@link DialogContextManagerListener} instance.
143      */
144     public void removeDialogContextManagerListener(DialogContextManagerListener listener);
145 
146 
147 }