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

For more information, please explore the Attic.

Coverage Report - org.apache.shale.dialog.DialogContextManager

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to you under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package org.apache.shale.dialog;
 
 import javax.faces.context.FacesContext;
 
 /**
  * <p>Management functions for the {@link DialogContext} instances related
  * to a particular user's session.</p>
  *
  * <p><strong>IMPLEMENTATION NOTE</strong> - Implementations of this interface
  * will be stored in session scope, so they should be serializable.</p>
  *
  * @since 1.0.4
  */
 public interface DialogContextManager {
 
 
     /**
      * <p>Create a new instance of the specified dialog configuration, returning
      * the newly created instance.  This instance must contain an
      * <code>id</code> value that is guaranteed to be unique among all active
      * instances for the current user.  The instance must also have been stored
      * as a request scope attribute under key <code>Constants.INSTANCE_BEAN</code>.
      * The new instance will not be associated with any parent instance.</p>
      *
      * @param context FacesContext for the current request
      * @param name Logical name of the dialog to be created
      * @return The newly created {@link DialogContext} instance, with no
      *         parent dialog association
      *
      * @exception IllegalArgumentException if no dialog definition
      * can be found for the specified logical name
      */
     public DialogContext create(FacesContext context, String name);
 
 
     /**
      * <p>Create a new instance of the specified dialog configuration, returning
      * the newly created instance.  This instance must contain an
      * <code>id</code> value that is guaranteed to be unique among all active
      * instances for the current user.  The instance must also have been stored
      * as a request scope attribute under key <code>Constants.INSTANCE_BEAN</code>.
      * The new instance will be associated with the specified parent instance,
      * which must be managed by this {@link DialogContextManager} and therefore
      * belong to the same user.</p>
      *
      * <p><strong>IMPLEMENTATION NOTE</strong> - Applications should generally
      * not call this method directly, because it will be awkward to associate
      * the newly created {@link DialogContext} instance with a different view
      * instance.  Instead, this method is primarily intended to support the
      * ability to automatically associate the {@link DialogContext} for, say,
      * a pop-up window with the {@link DialogContext} of the corresponding
      * main window.  This facility is supported automatically by the phase
      * listener that manages saving and restoring the association of a
      * {@link DialogContext} and its corresponding JSF view.</p>
      *
      * @param context FacesContext for the current request
      * @param name Logical name of the dialog to be executed
      * @param parent Parent DialogContext with which the new instance
      *  will be assocated (if any)
      * @return The newly created "child" {@link DialogContext} instance
      *
      * @exception IllegalArgumentException if no dialog definition
      *  can be found for the specified logical name
      * @exception IllegalStateException if the specified <code>parent</code>
      *  instance is not managed by this {@link DialogContextManager}
      */
     public DialogContext create(FacesContext context, String name,
                                 DialogContext parent);
 
 
     /**
      * <p>Return the {@link DialogContext} instance for the specified identifier
      * (if any); otherwise, return <code>null</code>.</p>
      *
      * @param id Dialog identifier for which to return an instance
      * @return The {@link DialogContext} instance for this identifier,
      *         may be null
      */
     public DialogContext get(String id);
 
 
     /**
      * <p>Remove the specified {@link DialogContext} instance from the set of
      * active instances for the current user.</p>
      *
      * @param instance {@link DialogContext} instance to be removed
      */
     public void remove(DialogContext instance);
 
 
     // ------------------------------------------ DialogContextManager Listeners
 
 
     /**
      * Register given {@link DialogContextManagerListener} for this
      * {@link DialogContextManager}.  Listener cannot be <code>null</code>.
      *
      * @param listener The {@link DialogContextManagerListener} instance.
      */
     public void addDialogContextManagerListener(DialogContextManagerListener listener);
 
 
     /**
      * Return the set of currently registered {@link DialogContextManagerListener}s.
      */
     public DialogContextManagerListener[] getDialogContextManagerListeners();
 
 
     /**
      * Remove this previously registered {@link DialogContextManagerListener}
      * for this {@link DialogContextManager}. The listener will no longer receive
      * any associated callbacks.
      *
      * @param listener The {@link DialogContextManagerListener} instance.
      */
     public void removeDialogContextManagerListener(DialogContextManagerListener listener);
 
 
 }

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		}