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

For more information, please explore the Attic.

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

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>Interface describing the current state of a particular dialog
  * context instance.</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 DialogContext {
 
 
     // ------------------------------------------------ DialogContext Properties
 
 
     /**
      * <p>Return <code>true</code> if this {@link DialogContext} is currently
      * active (created but not yet removed).</p>
      *
      * @return Whether this dialog instance is active
      */
     public boolean isActive();
 
 
     /**
      * <p>Return the generic data object representing model state for this
      * dialog instance.</p>
      *
      * @return The data object for this dialog instance
      */
     public Object getData();
 
 
     /**
      * <p>Set the generic data object representing model state for this
      * dialog instance.  As a value added feature, if the class of the
      * specified data object implements {@link DialogContextListener},
      * ensure that the data object is registered as a listener with this
      * {@link DialogContext}, and deregistered when the {@link DialogContext}
      * is completed (or this instance is replaced).</p>
      *
      * @param data The new data instance
      */
     public void setData(Object data);
 
 
     /**
      * <p>Return the context identifier for this instance of the specified
      * dialog.</p>
      *
      * @return The identifier for this dialog instance, unique for
      *         the manager associated with this dialog instance
      */
     public String getId();
 
 
     /**
      * <p>Return the logical name of the dialog being executed by this instance.<?p>
      *
      * @return The logical name of the dialog which this {@link DialogContext}
      *         is an instance of
      */
     public String getName();
 
 
     /**
      * <p>Return an opaque object containing any state information (besides the
      * context identifier, which is already saved) that this {@link DialogContext}
      * instance would like to have saved in the JavaServer Faces component tree,
      * and then restored (via a call to <code>setOpaqueData()</code> on the
      * subsequent form submit.  If there is no such information to be recorded,
      * return <code>null</code>.</p>
      *
      * <p><strong>IMPLEMENTATION NOTE</strong> - Because this object will be
      * stored as part of the JSF component tree, it must be <code>Serializable</code>.</p>
      *
      * <p><strong>WARNING</strong> - This method should <strong>ONLY</strong>
      * be called by the dialog framework infrastructure.  It should
      * <strong>NOT</strong> be called by the application.</p>
      */
     public Object getOpaqueState();
 
 
     /**
      * <p>Restore state information that was previously returned by a call to
      * <code>getOpaqueState()</code> on this {@link DialogContext} instance.
      * If the previous call to <code>getOpaqueState()</code> returned <code>null</code>,
      * this method will <strong>NOT</strong> be called.</p>
      *
      * <p><strong>WARNING</strong> - This method should <strong>ONLY</strong>
      * be called by the dialog framework infrastructure.  It should
      * <strong>NOT</strong> be called by the application.</p>
      *
      * @param opaqueState The opaque state object that was previously returned
      *  by a call to <code>getOpaqueState()</code> after potentially being
      *  serialized and deserialized by the JSF state saving functionality
      */
     public void setOpaqueState(Object opaqueState);
 
 
     /**
      * <p>Return the parent {@link DialogContext} instance associated with this
      * child {@link DialogContext}, if any; otherwise, return <code>null</code>.</p>
      *
      * @exception IllegalStateException if a parent {@link DialogContext} initially
      *  associated with this {@link DialogContext} is no longer available
      * @return The parent {@link DialogContext}, may be null
      */
     public DialogContext getParent();
 
 
     // --------------------------------------------------- DialogContext Methods
 
 
     /**
      * <p>Advance the execution of this {@link DialogContext} instance,
      * until an interaction with the user is required.  At that
      * point, navigate to the appropriate view, call
      * <code>FacesContext.renderResponse()</code>, and return.</p>
      *
      * @param context FacesContext for the current request
      * @param outcome Logical outcome to use for driving a transition
      *  out of a state that was waiting for user input, or <code>null</code>
      *  if no transition should be performed
      *
      * @exception IllegalStateException if this {@link DialogContext}
      *  instance has not yet been started
      */
     public void advance(FacesContext context, String outcome);
 
 
     /**
      * <p>Start the execution of this {@link DialogContext} instance,
      * advancing until an interaction with the user is required.
      * At that point, navigate to the appropriate view, call
      * <code>FacesContext.renderResopnse()</code>, and return.</p>
      *
      * @param context FacesContext for the current request
      *
      * @exception IllegalStateException if this {@link DialogContext}
      *  instance has already been started
      */
     public void start(FacesContext context);
 
 
     /**
      * <p>Stop the execution of this {@link DialogContext} instance,
      * resulting in no currently active dialog for the current
      * JavaServer Faces view.</p>
      *
      * @param context FacesContext for the current request
      *
      * @exception IllegalStateException if this {@link DialogContext}
      *  instance has not yet been started
      */
     public void stop(FacesContext context);
 
 
     // ------------------------------------------------- DialogContext Listeners
 
 
     /**
      * Register given {@link DialogContextListener} for this {@link DialogContext}.
      * Listener cannot be <code>null</code>.
      *
      * @param listener The {@link DialogContextListener} instance.
      */
     public void addDialogContextListener(DialogContextListener listener);
 
 
     /**
      * Return the set of currently registered {@link DialogContextListener}s.
      */
     public DialogContextListener[] getDialogContextListeners();
 
 
     /**
      * Remove this previously registered {@link DialogContextListener} for this
      * {@link DialogContext}. The listener will no longer receive any
      * associated callbacks.
      *
      * @param listener The {@link DialogContextListener} instance.
      */
     public void removeDialogContextListener(DialogContextListener 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>Interface describing the current state of a particular dialog
24		* context instance.</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 DialogContext {
32
33
34		// ------------------------------------------------ DialogContext Properties
35
36
37		/**
38		* <p>Return <code>true</code> if this {@link DialogContext} is currently
39		* active (created but not yet removed).</p>
40		*
41		* @return Whether this dialog instance is active
42		*/
43		public boolean isActive();
44
45
46		/**
47		* <p>Return the generic data object representing model state for this
48		* dialog instance.</p>
49		*
50		* @return The data object for this dialog instance
51		*/
52		public Object getData();
53
54
55		/**
56		* <p>Set the generic data object representing model state for this
57		* dialog instance. As a value added feature, if the class of the
58		* specified data object implements {@link DialogContextListener},
59		* ensure that the data object is registered as a listener with this
60		* {@link DialogContext}, and deregistered when the {@link DialogContext}
61		* is completed (or this instance is replaced).</p>
62		*
63		* @param data The new data instance
64		*/
65		public void setData(Object data);
66
67
68		/**
69		* <p>Return the context identifier for this instance of the specified
70		* dialog.</p>
71		*
72		* @return The identifier for this dialog instance, unique for
73		* the manager associated with this dialog instance
74		*/
75		public String getId();
76
77
78		/**
79		* <p>Return the logical name of the dialog being executed by this instance.<?p>
80		*
81		* @return The logical name of the dialog which this {@link DialogContext}
82		* is an instance of
83		*/
84		public String getName();
85
86
87		/**
88		* <p>Return an opaque object containing any state information (besides the
89		* context identifier, which is already saved) that this {@link DialogContext}
90		* instance would like to have saved in the JavaServer Faces component tree,
91		* and then restored (via a call to <code>setOpaqueData()</code> on the
92		* subsequent form submit. If there is no such information to be recorded,
93		* return <code>null</code>.</p>
94		*
95		* <p><strong>IMPLEMENTATION NOTE</strong> - Because this object will be
96		* stored as part of the JSF component tree, it must be <code>Serializable</code>.</p>
97		*
98		* <p><strong>WARNING</strong> - This method should <strong>ONLY</strong>
99		* be called by the dialog framework infrastructure. It should
100		* <strong>NOT</strong> be called by the application.</p>
101		*/
102		public Object getOpaqueState();
103
104
105		/**
106		* <p>Restore state information that was previously returned by a call to
107		* <code>getOpaqueState()</code> on this {@link DialogContext} instance.
108		* If the previous call to <code>getOpaqueState()</code> returned <code>null</code>,
109		* this method will <strong>NOT</strong> be called.</p>
110		*
111		* <p><strong>WARNING</strong> - This method should <strong>ONLY</strong>
112		* be called by the dialog framework infrastructure. It should
113		* <strong>NOT</strong> be called by the application.</p>
114		*
115		* @param opaqueState The opaque state object that was previously returned
116		* by a call to <code>getOpaqueState()</code> after potentially being
117		* serialized and deserialized by the JSF state saving functionality
118		*/
119		public void setOpaqueState(Object opaqueState);
120
121
122		/**
123		* <p>Return the parent {@link DialogContext} instance associated with this
124		* child {@link DialogContext}, if any; otherwise, return <code>null</code>.</p>
125		*
126		* @exception IllegalStateException if a parent {@link DialogContext} initially
127		* associated with this {@link DialogContext} is no longer available
128		* @return The parent {@link DialogContext}, may be null
129		*/
130		public DialogContext getParent();
131
132
133		// --------------------------------------------------- DialogContext Methods
134
135
136		/**
137		* <p>Advance the execution of this {@link DialogContext} instance,
138		* until an interaction with the user is required. At that
139		* point, navigate to the appropriate view, call
140		* <code>FacesContext.renderResponse()</code>, and return.</p>
141		*
142		* @param context FacesContext for the current request
143		* @param outcome Logical outcome to use for driving a transition
144		* out of a state that was waiting for user input, or <code>null</code>
145		* if no transition should be performed
146		*
147		* @exception IllegalStateException if this {@link DialogContext}
148		* instance has not yet been started
149		*/
150		public void advance(FacesContext context, String outcome);
151
152
153		/**
154		* <p>Start the execution of this {@link DialogContext} instance,
155		* advancing until an interaction with the user is required.
156		* At that point, navigate to the appropriate view, call
157		* <code>FacesContext.renderResopnse()</code>, and return.</p>
158		*
159		* @param context FacesContext for the current request
160		*
161		* @exception IllegalStateException if this {@link DialogContext}
162		* instance has already been started
163		*/
164		public void start(FacesContext context);
165
166
167		/**
168		* <p>Stop the execution of this {@link DialogContext} instance,
169		* resulting in no currently active dialog for the current
170		* JavaServer Faces view.</p>
171		*
172		* @param context FacesContext for the current request
173		*
174		* @exception IllegalStateException if this {@link DialogContext}
175		* instance has not yet been started
176		*/
177		public void stop(FacesContext context);
178
179
180		// ------------------------------------------------- DialogContext Listeners
181
182
183		/**
184		* Register given {@link DialogContextListener} for this {@link DialogContext}.
185		* Listener cannot be <code>null</code>.
186		*
187		* @param listener The {@link DialogContextListener} instance.
188		*/
189		public void addDialogContextListener(DialogContextListener listener);
190
191
192		/**
193		* Return the set of currently registered {@link DialogContextListener}s.
194		*/
195		public DialogContextListener[] getDialogContextListeners();
196
197
198		/**
199		* Remove this previously registered {@link DialogContextListener} for this
200		* {@link DialogContext}. The listener will no longer receive any
201		* associated callbacks.
202		*
203		* @param listener The {@link DialogContextListener} instance.
204		*/
205		public void removeDialogContextListener(DialogContextListener listener);
206
207
208		}