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  
21  /***
22   * <p>JavaBeans listener for a single instance of a Shale dialog.</p>
23   *
24   * <p><strong>IMPLEMENTATION NOTE</strong> - Implementations of this interface
25   * will be stored in session scope, so they should be serializable.</p>
26   *
27   * @since 1.0.4
28   */
29  public interface DialogContextListener {
30  
31  
32      //----------------------------------------------- Coarse grained callbacks
33  
34      /***
35       * <p>Handle the starting of the dialog instance.</p>
36       */
37      public void onStart();
38  
39  
40      /***
41       * <p>Handle the stopping of the dialog instance.</p>
42       */
43      public void onStop();
44  
45  
46      /***
47       * <p>Handle an unexpected failure during the execution of this dialg
48       * instance.</p>
49       *
50       * @param exception A potentially implementation specific exception
51       *                  during the execution of this dialog instance
52       */
53      public void onException(Exception exception);
54  
55  
56      // ---------------------------------------------- Medium grained callbacks
57  
58  
59      /***
60       * <p>Handle our parent {@link DialogContext} instance being placed
61       * into service for the current request.  This will occur when a
62       * dialog is newly created (by any of the available means), or when
63       * it is recognized, during a subsequent postback, that there is a
64       * currently active dialog identiier.</p>
65       *
66       * <p><strong>NOTE</strong> - For a newly created {@link DialogContext}
67       * instance, this event will be fired <strong>after</strong> the
68       * instance has been started (and, therefore, after an <code>onStart()</code>
69       * callback to this listener).</p>
70       *
71       * @since 1.1.0
72       */
73      public void onActivate();
74  
75  
76      /***
77       * <p>Handle our parent {@link DialogContext} instance being taken out
78       * of service at the end of a request.  The response for this request
79       * has already been rendered, so any changes to the JSF component tree
80       * will not have any effect.</p>
81       *
82       * <p><strong>NOTE</strong> - For a {@link DialogContext} instance being
83       * stopped, this event will be fired <strong>before</strong> the
84       * instance has been started (and, therefore, before an <code>onStop()</code>
85       * callback to this listener).</p>
86       *
87       * @since 1.1.0
88       */
89      public void onPassivate();
90  
91  
92      //------------------------------------------------- Fine grained callbacks
93  
94      /***
95       * <p>Handle an entry into a dialog state.</p>
96       *
97       * @param stateId Implementation specific identifier of the state
98       *                that has been entered
99       */
100     public void onEntry(String stateId);
101 
102 
103     /***
104      * <p>Handle an exit from a dialog state.</p>
105      *
106      * @param stateId Implementation specific identifier of the state
107      *                that has been exited
108      */
109     public void onExit(String stateId);
110 
111 
112     /***
113      * <p>Handle a transition being followed.</p>
114      *
115      * @param fromStateId Implementation specific identifier of the source
116      *                    state for the transition that has been followed
117      * @param toStateId Implementation specific identifier of the target
118      *                  state for the transition that has been followed
119      */
120     public void onTransition(String fromStateId, String toStateId);
121 
122 
123     //-------------------------------------------------------------- Ownership
124 
125     /***
126      * <p>Return the {@link DialogContext} instance associated with this
127      * {@link DialogContextListener}.</p>
128      *
129      * @return The {@link DialogContext} whose execution we are listening to
130      */
131     public DialogContext getDialogContext();
132 
133 
134     /***
135      * <p>Set the {@link DialogContext} instance associated with this
136      * {@link DialogContextListener}.</p>
137      *
138      * @param dialogContext The {@link DialogContext} whose execution we
139      *                      will track
140      */
141     public void setDialogContext(DialogContext dialogContext);
142 
143 
144 }