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.server.watch;
20 
21 import java.io.PrintWriter;
22 import org.apache.zookeeper.Watcher;
23 import org.apache.zookeeper.Watcher.Event.EventType;
24 
25 public interface IWatchManager {
26 
27     /**
28      * Add watch to specific path.
29      *
30      * @param path znode path
31      * @param watcher watcher object reference
32      *
33      * @return true if the watcher added is not already present
34      */
addWatch(String path, Watcher watcher)35     boolean addWatch(String path, Watcher watcher);
36 
37     /**
38      * Add watch to specific path.
39      *
40      * @param path znode path
41      * @param watcher watcher object reference
42      * @param watcherMode the watcher mode to use
43      *
44      * @return true if the watcher added is not already present
45      */
addWatch(String path, Watcher watcher, WatcherMode watcherMode)46     default boolean addWatch(String path, Watcher watcher, WatcherMode watcherMode) {
47         if (watcherMode == WatcherMode.DEFAULT_WATCHER_MODE) {
48             return addWatch(path, watcher);
49         }
50         throw new UnsupportedOperationException();  // custom implementations must defeat this
51     }
52 
53     /**
54      * Checks the specified watcher exists for the given path.
55      *
56      * @param path znode path
57      * @param watcher watcher object reference
58      *
59      * @return true if the watcher exists, false otherwise
60      */
containsWatcher(String path, Watcher watcher)61     boolean containsWatcher(String path, Watcher watcher);
62 
63     /**
64      * Removes the specified watcher for the given path.
65      *
66      * @param path znode path
67      * @param watcher watcher object reference
68      *
69      * @return true if the watcher successfully removed, false otherwise
70      */
removeWatcher(String path, Watcher watcher)71     boolean removeWatcher(String path, Watcher watcher);
72 
73     /**
74      * The entry to remove the watcher when the cnxn is closed.
75      *
76      * @param watcher watcher object reference
77      */
removeWatcher(Watcher watcher)78     void removeWatcher(Watcher watcher);
79 
80     /**
81      * Distribute the watch event for the given path.
82      *
83      * @param path znode path
84      * @param type the watch event type
85      *
86      * @return the watchers have been notified
87      */
triggerWatch(String path, EventType type)88     WatcherOrBitSet triggerWatch(String path, EventType type);
89 
90     /**
91      * Distribute the watch event for the given path, but ignore those
92      * suppressed ones.
93      *
94      * @param path znode path
95      * @param type the watch event type
96      * @param suppress the suppressed watcher set
97      *
98      * @return the watchers have been notified
99      */
triggerWatch(String path, EventType type, WatcherOrBitSet suppress)100     WatcherOrBitSet triggerWatch(String path, EventType type, WatcherOrBitSet suppress);
101 
102     /**
103      * Get the size of watchers.
104      *
105      * @return the watchers number managed in this class.
106      */
size()107     int size();
108 
109     /**
110      * Clean up the watch manager.
111      */
shutdown()112     void shutdown();
113 
114     /**
115      * Returns a watch summary.
116      *
117      * @return watch summary
118      * @see WatchesSummary
119      */
getWatchesSummary()120     WatchesSummary getWatchesSummary();
121 
122     /**
123      * Returns a watch report.
124      *
125      * @return watch report
126      * @see WatchesReport
127      */
getWatches()128     WatchesReport getWatches();
129 
130     /**
131      * Returns a watch report by path.
132      *
133      * @return watch report
134      * @see WatchesPathReport
135      */
getWatchesByPath()136     WatchesPathReport getWatchesByPath();
137 
138     /**
139      * String representation of watches. Warning, may be large!
140      *
141      * @param pwriter the writer to dump the watches
142      * @param byPath iff true output watches by paths, otw output
143      * watches by connection
144      *
145      */
dumpWatches(PrintWriter pwriter, boolean byPath)146     void dumpWatches(PrintWriter pwriter, boolean byPath);
147 
148     /**
149      * Return the current number of recursive watchers
150      *
151      * @return qty
152      */
getRecursiveWatchQty()153     default int getRecursiveWatchQty() {
154         return 0;
155     }
156 }
157