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.basic.model;
19  
20  import java.util.Iterator;
21  
22  /***
23   * <p>Overall configuration of an individual dialog.  During application
24   * execution, this information is immutable (so that simultaneous execution
25   * threads may be processing states or transitions through this dialog).
26   * Therefore, access to configuration information is not synchronized.</p>
27   *
28   * <p>A {@link Dialog} is characterized by a set of named {@link State}s,
29   * which are executed in an order that is determined by {@link Transition}s
30   * between those {@link State}s.  Execution of a {@link Dialog} begins at
31   * the {@link State} specified by the <code>start</code> property, and ends
32   * when an {@link EndState} is executed.</p>
33   *
34   * <p>{@link Transition}s describe the rule that determines the name of the
35   * next {@link State} to be executed, based upon a logical outcome returned
36   * by the execution of a previous {@link State}.  {@link Transition}s
37   * associated with a {@link Dialog} define dialog-wide rules for specified
38   * outcomes, while {@link Transition}s associated with a particular
39   * {@link State} can replace the global {@link Transition} that would normally
40   * be selected with one specific to the executing {@link State}.</p>
41   *
42   * @since 1.0.4
43   */
44  
45  public interface Dialog {
46  
47  
48      // -------------------------------------------------------------- Properties
49  
50  
51      /***
52       * <p>Return the class of a JavaBean to be instantiated as the initial
53       * value of the <code>data</code> property of a newly instantiated
54       * <code>DialogContext</code>.</p>
55       *
56       * <p>If not explicitly specified in the configuration metadata, this
57       * should default to <code>java.util.HashMap</code> to provide convenient
58       * name/value pair storage.</p>
59       *
60       * <p><strong>IMPLEMENTATION NOTE</strong> - Because the <code>data</code>
61       * object of <code>DialogContext</code> instances is stored in session
62       * scope, the <code>Class</code> specified here should be serializable.</p>
63       *
64       * @return The JavaBean class whose instance becomes the <code>data</code>
65       *         property of a new instance of this dialog
66       */
67      public Class getDataClass();
68  
69  
70      /***
71       * <p>Return the name of this {@link Dialog}.</p>
72       *
73       * @return The name of this {@link Dialog}
74       */
75      public String getName();
76  
77  
78      /***
79       * <p>Return the name of the starting {@link State} for this
80       * {@link Dialog}.</p>
81       *
82       * @return The starting state associated with this {@link Dialog}
83       */
84      public String getStart();
85  
86  
87      /***
88       * <p>Return an <code>Iterator</code> over the names of {@link State}s
89       * that are owned by this {@link Dialog}.  If there are no such
90       * {@link State}s, an empty <code>Iterator</code> is returned.</p>
91       *
92       * @return An <code>Iterator</code> over all the {@link State}s in this
93       *         {@link Dialog}
94       */
95      public Iterator getStateIds();
96  
97  
98      /***
99       * <p>Return an <code>Iterator</code> over the logical outcomes of
100      * global {@link Transition}s for this {@link Dialog}.  If there are
101      * no such {@link Transition}s, an empty <code>Iterator</code> is
102      * returned.</p>
103      *
104      * @return An <code>Iterator</code> over the logical outcomes of global
105      *         {@link Transition}s for this {@link Dialog}
106      */
107     public Iterator getTransitionOutcomes();
108 
109 
110     // ---------------------------------------------------------- Public Methods
111 
112 
113     /***
114      * <p>Return the specified {@link State}, owned by this {@link Dialog},
115      * if any.  Otherwise, return <code>null</code>.</p>
116      *
117      * @param id Identifier of the requested {@link State}
118      * @return The {@link State} specified by the identifier, may be null
119      */
120     public State findState(String id);
121 
122 
123     /***
124      * <p>Return the global {@link Transition} for the specified logical outcome,
125      * if any; otherwise, return <code>null</code>.</p>
126      *
127      * @param outcome Logical outcome for which to return a {@link Transition}
128      * @return The global {@link Transition} for the specified logical outcome
129      */
130     public Transition findTransition(String outcome);
131 
132 
133 }