1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  You may obtain a copy of the License at
9  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 package org.apache.zookeeper;
20 
21 import org.apache.yetus.audience.InterfaceAudience;
22 
23 /**
24  * This interface specifies the public interface an event handler class must
25  * implement. A ZooKeeper client will get various events from the ZooKeeper
26  * server it connects to. An application using such a client handles these
27  * events by registering a callback object with the client. The callback object
28  * is expected to be an instance of a class that implements Watcher interface.
29  *
30  */
31 @InterfaceAudience.Public
32 public interface Watcher {
33 
34     /**
35      * This interface defines the possible states an Event may represent
36      */
37     @InterfaceAudience.Public
38     interface Event {
39 
40         /**
41          * Enumeration of states the ZooKeeper may be at the event
42          */
43         @InterfaceAudience.Public
44         enum KeeperState {
45             /** Unused, this state is never generated by the server */
46             @Deprecated
47             Unknown(-1),
48 
49             /** The client is in the disconnected state - it is not connected
50              * to any server in the ensemble. */
51             Disconnected(0),
52 
53             /** Unused, this state is never generated by the server */
54             @Deprecated
55             NoSyncConnected(1),
56 
57             /** The client is in the connected state - it is connected
58              * to a server in the ensemble (one of the servers specified
59              * in the host connection parameter during ZooKeeper client
60              * creation). */
61             SyncConnected(3),
62 
63             /**
64              * Auth failed state
65              */
66             AuthFailed(4),
67 
68             /**
69              * The client is connected to a read-only server, that is the
70              * server which is not currently connected to the majority.
71              * The only operations allowed after receiving this state is
72              * read operations.
73              * This state is generated for read-only clients only since
74              * read/write clients aren't allowed to connect to r/o servers.
75              */
76             ConnectedReadOnly(5),
77 
78             /**
79              * SaslAuthenticated: used to notify clients that they are SASL-authenticated,
80              * so that they can perform Zookeeper actions with their SASL-authorized permissions.
81              */
82             SaslAuthenticated(6),
83 
84             /** The serving cluster has expired this session. The ZooKeeper
85              * client connection (the session) is no longer valid. You must
86              * create a new client connection (instantiate a new ZooKeeper
87              * instance) if you with to access the ensemble. */
88             Expired(-112),
89 
90             /**
91              * The client has been closed. This state is never generated by
92              * the server, but is generated locally when a client calls
93              * {@link ZooKeeper#close()} or {@link ZooKeeper#close(int)}
94              */
95             Closed(7);
96 
97             private final int intValue;     // Integer representation of value
98             // for sending over wire
99 
KeeperState(int intValue)100             KeeperState(int intValue) {
101                 this.intValue = intValue;
102             }
103 
getIntValue()104             public int getIntValue() {
105                 return intValue;
106             }
107 
fromInt(int intValue)108             public static KeeperState fromInt(int intValue) {
109                 switch (intValue) {
110                 case -1:
111                     return KeeperState.Unknown;
112                 case 0:
113                     return KeeperState.Disconnected;
114                 case 1:
115                     return KeeperState.NoSyncConnected;
116                 case 3:
117                     return KeeperState.SyncConnected;
118                 case 4:
119                     return KeeperState.AuthFailed;
120                 case 5:
121                     return KeeperState.ConnectedReadOnly;
122                 case 6:
123                     return KeeperState.SaslAuthenticated;
124                 case -112:
125                     return KeeperState.Expired;
126                 case 7:
127                     return KeeperState.Closed;
128 
129                 default:
130                     throw new RuntimeException("Invalid integer value for conversion to KeeperState");
131                 }
132             }
133         }
134 
135         /**
136          * Enumeration of types of events that may occur on the ZooKeeper
137          */
138         @InterfaceAudience.Public
139         enum EventType {
140             None(-1),
141             NodeCreated(1),
142             NodeDeleted(2),
143             NodeDataChanged(3),
144             NodeChildrenChanged(4),
145             DataWatchRemoved(5),
146             ChildWatchRemoved(6),
147             PersistentWatchRemoved (7);
148 
149             private final int intValue;     // Integer representation of value
150             // for sending over wire
151 
EventType(int intValue)152             EventType(int intValue) {
153                 this.intValue = intValue;
154             }
155 
getIntValue()156             public int getIntValue() {
157                 return intValue;
158             }
159 
fromInt(int intValue)160             public static EventType fromInt(int intValue) {
161                 switch (intValue) {
162                 case -1:
163                     return EventType.None;
164                 case 1:
165                     return EventType.NodeCreated;
166                 case 2:
167                     return EventType.NodeDeleted;
168                 case 3:
169                     return EventType.NodeDataChanged;
170                 case 4:
171                     return EventType.NodeChildrenChanged;
172                 case 5:
173                     return EventType.DataWatchRemoved;
174                 case 6:
175                     return EventType.ChildWatchRemoved;
176                 case 7:
177                     return EventType.PersistentWatchRemoved;
178 
179                 default:
180                     throw new RuntimeException("Invalid integer value for conversion to EventType");
181                 }
182             }
183         }
184 
185     }
186 
187     /**
188      * Enumeration of types of watchers
189      */
190     @InterfaceAudience.Public
191     enum WatcherType {
192         Children(1),
193         Data(2),
194         Any(3);
195 
196         // Integer representation of value
197         private final int intValue;
198 
WatcherType(int intValue)199         WatcherType(int intValue) {
200             this.intValue = intValue;
201         }
202 
getIntValue()203         public int getIntValue() {
204             return intValue;
205         }
206 
fromInt(int intValue)207         public static WatcherType fromInt(int intValue) {
208             switch (intValue) {
209             case 1:
210                 return WatcherType.Children;
211             case 2:
212                 return WatcherType.Data;
213             case 3:
214                 return WatcherType.Any;
215 
216             default:
217                 throw new RuntimeException("Invalid integer value for conversion to WatcherType");
218             }
219         }
220     }
221 
process(WatchedEvent event)222     void process(WatchedEvent event);
223 
224 }
225