1 package com.github.triceo.splitlog.api;
2
3 import java.io.File;
4
5 /**
6 * The primary point of interaction with this tool. Allows users to start
7 * listening to changes in log files.
8 */
9 public interface LogWatch extends MessageProducer<LogWatch> {
10
11 /**
12 * The file that is being tracked by this class.
13 *
14 * @return Never null
15 */
16 File getWatchedFile();
17
18 /**
19 * Whether or not {@link #stopFollowing(Follower)} has been called for a
20 * given follower.
21 *
22 * @param follower
23 * Tailer in question.
24 * @return True if it has.
25 */
26 boolean isFollowedBy(final Follower follower);
27
28 /**
29 * Whether or not particular {@link MessageMeasure} is being automatically
30 * handed down to new {@link Follower}s.
31 *
32 * @param measure
33 * Measure in question.
34 * @return True after {@link #startHandingDown(MessageMeasure, String)} has
35 * been called and before {@link #stopHandingDown(MessageMeasure)}.
36 */
37 boolean isHandingDown(final MessageMeasure<? extends Number, Follower> measure);
38
39 /**
40 * Whether or not particular {@link MessageMeasure} is being automatically
41 * handed down to new {@link Follower}s.
42 *
43 * @param id
44 * ID in question.
45 * @return True after {@link #startHandingDown(MessageMeasure, String)} has
46 * been called and before {@link #stopHandingDown(String)}.
47 */
48 boolean isHandingDown(final String id);
49
50 /**
51 * Whether or not {@link #start()} has been called.
52 *
53 * @return True if it has.
54 */
55 boolean isStarted();
56
57 /**
58 * Whether or not {@link #stop()} has been called.
59 *
60 * @return True if it has.
61 */
62 boolean isStopped();
63
64 /**
65 * Start tailing the log file.
66 *
67 * @return True if just started, false if already started.
68 */
69 boolean start();
70
71 /**
72 * Begin watching for new messages from this point in time.
73 *
74 * @return API for watching for messages.
75 */
76 Follower startFollowing();
77
78 /**
79 * Every new {@link Follower} from now on will immediately receive a new
80 * {@link MessageMetric} instance with a given ID that is using the given
81 * measure instance.
82 *
83 * @param measure
84 * Measure to use in the newly created {@link MessageMetric}
85 * instance.
86 * @param id
87 * The ID to locate the {@link MessageMetric} using
88 * {@link Follower#getMetric(String)}. No relation to the ID used
89 * by {@link #startMeasuring(MessageMeasure, String)}.
90 * @return False if either the measure or the ID is already being handed
91 * down.
92 */
93 boolean startHandingDown(final MessageMeasure<? extends Number, Follower> measure, final String id);
94
95 /**
96 * Stop all followers from following and free resources. Will terminate
97 * every running measurement via {@link MessageMetric}.
98 *
99 * @return True if terminated as a result, false if already terminated.
100 */
101 boolean stop();
102
103 /**
104 * Stop particular follower from following.
105 *
106 * @param follower
107 * This follower will receive no more messages.
108 * @return True if terminated as a result, false if already terminated.
109 */
110 boolean stopFollowing(final Follower follower);
111
112 /**
113 * Invalidate {@link #startHandingDown(MessageMeasure, String)}. No further
114 * {@link Follower} will automatically receive {@link MessageMetric} using
115 * this measure by default.
116 *
117 * @param measure
118 * The measure to no longer be handing down to newly instantiated
119 * {@link Follower}s.
120 * @return False if it wasn't being handed down.
121 */
122 boolean stopHandingDown(final MessageMeasure<? extends Number, Follower> measure);
123
124 /**
125 * Invalidate {@link #startHandingDown(MessageMeasure, String)}. No further
126 * {@link Follower} will automatically receive {@link MessageMetric} using
127 * this measure by default.
128 *
129 * @param id
130 * The ID of the {@link MessageMeasure} to no longer be handing
131 * down to newly instantiated {@link Follower}s. No relation to
132 * the ID used by {@link #startMeasuring(MessageMeasure, String)}
133 * .
134 * @return False if it wasn't being handed down.
135 */
136 boolean stopHandingDown(final String id);
137
138 }