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 
17 package com.android.camera.captureintent.stateful;
18 
19 import com.google.common.annotations.VisibleForTesting;
20 import com.google.common.base.Optional;
21 
22 import 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
29 public 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      */
getStateMachine()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      */
onEnter()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      */
onLeave()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
getEventHandlerCount()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      */
getEventHandler(Class<T> eventClass)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      */
setEventHandler( Class<T> eventClass, EventHandler<T> eventHandler)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      */
removeEventHandler(Class<T> eventClass)87     public <T extends Event> void removeEventHandler(Class<T> eventClass);
88 }