1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.camera.captureintent.stateful;
18
19import com.google.common.annotations.VisibleForTesting;
20import com.google.common.base.Optional;
21
22import javax.annotation.ParametersAreNonnullByDefault;
23
24/**
25 * Defines an state interface that any implementation of the interface can be
26 * operated by {@link StateMachine}.
27 */
28@ParametersAreNonnullByDefault
29public interface State {
30
31    public static Optional<State> NO_CHANGE = Optional.absent();
32
33    /**
34     * Obtains the associated state machine.
35     *
36     * @return The associated state machine.
37     */
38    public StateMachine getStateMachine();
39
40    /**
41     * Notifies the state that the state machine is about to transition into
42     * the state.
43     *
44     * @return The next desired state. If it is not NO_CHANGE, the state
45     * machine will change to the next desired state immediately.
46     */
47    public Optional<State> onEnter();
48
49    /**
50     * Notifies the state that the state machine is about to transition out
51     * from this state to another state. The state has to release all resources
52     * it holds at this point.
53     */
54    public void onLeave();
55
56    /**
57     * Obtains the number of registered event handlers in the state.
58     *
59     * @return The number of registered event handlers in the state.
60     */
61    @VisibleForTesting
62    public int getEventHandlerCount();
63
64    /**
65     * Obtains the event handler for a particular type of event.
66     *
67     * @param eventClass The type of the event.
68     * @return An event handler that is able to process the event. Null if the
69     * state doesn't observe the event.
70     */
71    public <T extends Event> EventHandler<T> getEventHandler(Class<T> eventClass);
72
73    /**
74     * Specifies a handler for a particular type of event.
75     *
76     * @param eventClass   The event class.
77     * @param eventHandler The event handler.
78     */
79    public <T extends Event> void setEventHandler(
80            Class<T> eventClass, EventHandler<T> eventHandler);
81
82    /**
83     * Removes the handler for a specific type of event.
84     *
85     * @param eventClass The event class.
86     */
87    public <T extends Event> void removeEventHandler(Class<T> eventClass);
88}