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>A {@link State} is an executable entity, within the scope of an
24   * owning {@link Dialog}.  Execution of a {@link State} returns a logical
25   * outcome (represented as a String), which is used to select the next
26   * {@link State} to be executed, via a {@link Transition}.</p>
27   *
28   * <p>Specialized subinterfaces of {@link State} are defined for the
29   * standard execution entity types that are supported, including:</p>
30   * <ul>
31   * <li>{@link ActionState} - Execution of an action method (typically
32   *     delegating behavior to appropriate business logic).</li>
33   * <li>{@link SubdialogState} - Execution of a separate {@link Dialog},
34   *     with continuation based on the logical outcome returned by the
35   *     ending {@link State} within the subordinate dialog.</li>
36   * <li>{@link ViewState} - Execution of the rendering of a JavaServer
37   *     Faces <code>view</code>, and returning the logical outcome returned
38   *     by the action method that processes the subsequent submit.</li>
39   * <li>{@link EndState} - Specialized {@link ViewState} that also marks
40   *     the end of execution of this {@link Dialog}.</li>
41   * </ul>
42   *
43   * @since 1.0.4
44   */
45  
46  public interface State {
47  
48  
49      // -------------------------------------------------------------- Properties
50  
51  
52      /***
53       * <p>Return the {@link Dialog} that owns this {@link State}.</p>
54       *
55       * @return The {@link Dialog} this {@link State} belongs to
56       */
57      public Dialog getDialog();
58  
59  
60      /***
61       * <p>Return the identifier of this {@link State}, which must be unique
62       * among the {@link State}s owned by the same {@link Dialog}.</p>
63       *
64       * @return The identifier for this {@link State}
65       */
66      public String getName();
67  
68  
69      /***
70       * <p>Return an <code>Iterator</code> over the logical outcomes of
71       * local {@link Transition}s for this {@link State}.  If there are
72       * no such {@link Transition}s, an empty <code>Iterator</code> is
73       * returned.</p>
74       *
75       * @return An {@link Iterator} over the logical outcomes of local
76       *         {@link Transition}s for this {@link State}
77       */
78      public Iterator getTransitionOutcomes();
79  
80  
81      // ---------------------------------------------------------- Public Methods
82  
83  
84      /***
85       * <p>Return the {@link Transition} for the specified logical outcome,
86       * if any; otherwise, return <code>null</code>.</p>
87       *
88       * @param outcome Logical outcome for which to return a {@link Transition}
89       * @return The {@link Transition} for the specified outcome, may be null
90       */
91      public Transition findTransition(String outcome);
92  
93  
94  }