1 package com.github.triceo.splitlog.api;
2
3 import java.io.OutputStream;
4 import java.util.SortedSet;
5 import java.util.concurrent.TimeUnit;
6
7 /**
8 * Follower's primary function is to allow users to work with their portion of
9 * the tailed log file. It provides means for a blocking wait for particular
10 * chunks, and can also send these chunks to output.
11 *
12 * Messages get into the follower when {@link LogWatch} notifies it of them.
13 * Alternatively, each {@link Follower#tag(String)} will create a Message within
14 * the follower and not notify anyone.
15 */
16 public interface CommonFollower {
17
18 /**
19 * Retrieve messages that this follower has been notified of, and tags. They
20 * will appear in the order in which we have been notified of them.
21 *
22 * @return Messages we have been notified of, and tags.
23 */
24 SortedSet<Message> getMessages();
25
26 /**
27 * Retrieve messages that this follower has been notified of, and tags, in a
28 * given order.
29 *
30 * @param order
31 * The comparator that will be used to order the messages.
32 * @return Messages we have been notified of, and tags.
33 */
34 SortedSet<Message> getMessages(MessageComparator order);
35
36 /**
37 * Retrieve messages that this follower has been notified of, if a certain
38 * condition holds true for them, and tags. They will be in the order given.
39 *
40 * @param condition
41 * The condition.
42 * @return Messages we have been notified of, for which the condition holds
43 * true, and tags.
44 */
45 SortedSet<Message> getMessages(final SimpleMessageCondition condition);
46
47 /**
48 * Retrieve messages that this follower has been notified of, if a certain
49 * condition holds true for them, and tags. They will be in the order in
50 * which we have been notified of them.
51 *
52 * @param condition
53 * The condition.
54 * @param order
55 * The comparator that will be used to order the messages.
56 * @return Messages we have been notified of, for which the condition holds
57 * true, and tags.
58 */
59 SortedSet<Message> getMessages(final SimpleMessageCondition condition, final MessageComparator order);
60
61 /**
62 * Merge this {@link CommonFollower} with another. This
63 * {@link CommonFollower} has a responsibility of notifying the resulting
64 * {@link MergingFollower} of every {@link Message} that it receives, until
65 * such time that {@link MergingFollower#separate(Follower)} is called on
66 * it.
67 *
68 * @param f
69 * To merge with.
70 * @return A new {@link MergingFollower}, that will merge both
71 * {@link CommonFollower}s. If any of the {@link CommonFollower}s
72 * already is a {@link MergingFollower}, the returned instance will
73 * hold every merged {@link CommonFollower} individually and not
74 * compose {@link MergingFollower}s.
75 */
76 MergingFollower mergeWith(CommonFollower f);
77
78 /**
79 * Will block until a message arrives, for which the condition is true.
80 *
81 * @param condition
82 * Condition that needs to be true for the method to unblock.
83 * @return Null if the method unblocked due to some other reason.
84 */
85 Message waitFor(MidDeliveryMessageCondition condition);
86
87 /**
88 * Will block until a message arrives, for which the condition is true. If
89 * none arrives before the timeout, it unblocks anyway.
90 *
91 * @param condition
92 * Condition that needs to be true for the method to unblock.
93 * @param timeout
94 * Time before forcibly aborting.
95 * @param unit
96 * Unit of time.
97 * @return Null if the method unblocked due to some other reason.
98 */
99 Message waitFor(MidDeliveryMessageCondition condition, long timeout, TimeUnit unit);
100
101 /**
102 * Will write to a stream the result of {@link #getMessages()}, using a
103 * {@link MessageFormatter} implementation of its own choosing. Will close
104 * the stream.
105 *
106 * @param stream
107 * Target.
108 * @return True if written, false otherwise.
109 */
110 boolean write(final OutputStream stream);
111
112 /**
113 * Will write to a stream the result of
114 * {@link #getMessages(MessageComparator)}, using a {@link MessageFormatter}
115 * implementation of its own choosing. Will close the stream.
116 *
117 * @param stream
118 * Target.
119 * @param order
120 * The comparator to pass to
121 * {@link #getMessages(MessageComparator)}.
122 * @return True if written, false otherwise.
123 */
124 boolean write(final OutputStream stream, final MessageComparator order);
125
126 /**
127 * Will write to a stream the result of
128 * {@link #getMessages(MessageComparator)}, using given
129 * {@link MessageFormatter}. Will close the stream.
130 *
131 * @param stream
132 * Target.
133 * @param order
134 * The comparator to pass to
135 * {@link #getMessages(MessageComparator)}.
136 * @param formatter
137 * Formatter to use to transform message into string.
138 * @return True if written, false otherwise.
139 */
140 boolean write(final OutputStream stream, final MessageComparator order, final MessageFormatter formatter);
141
142 /**
143 * Will write to a stream the result of {@link #getMessages()}, using given
144 * {@link MessageFormatter}. Will close the stream.
145 *
146 * @param stream
147 * Target.
148 * @param formatter
149 * Formatter to use to transform message into string.
150 * @return True if written, false otherwise.
151 */
152 boolean write(final OutputStream stream, final MessageFormatter formatter);
153
154 /**
155 * Will write to a stream the result of
156 * {@link #getMessages(SimpleMessageCondition)}, using a
157 * {@link MessageFormatter} implementation of its own choosing. Will close
158 * the stream.
159 *
160 * @param stream
161 * Target.
162 * @param condition
163 * The condition to pass to
164 * {@link #getMessages(SimpleMessageCondition)}.
165 * @return True if written, false otherwise.
166 */
167 boolean write(final OutputStream stream, final SimpleMessageCondition condition);
168
169 /**
170 * Will write to a stream the result of
171 * {@link #getMessages(SimpleMessageCondition, MessageComparator)}, using a
172 * {@link MessageFormatter} implementation of its own choosing. Will close
173 * the stream.
174 *
175 * @param stream
176 * Target.
177 * @param condition
178 * The condition to pass to
179 * {@link #getMessages(SimpleMessageCondition, MessageComparator)}
180 * .
181 * @param order
182 * The comparator to pass to
183 * {@link #getMessages(SimpleMessageCondition, MessageComparator)}
184 * .
185 * @return True if written, false otherwise.
186 */
187 boolean write(final OutputStream stream, final SimpleMessageCondition condition, final MessageComparator order);
188
189 /**
190 * Will write to a stream the result of
191 * {@link #getMessages(SimpleMessageCondition, MessageComparator)}, using
192 * given {@link MessageFormatter}. Will close the stream.
193 *
194 * @param stream
195 * Target.
196 * @param condition
197 * The condition to pass to
198 * {@link #getMessages(SimpleMessageCondition, MessageComparator)}
199 * .
200 * @param order
201 * The comparator to pass to
202 * {@link #getMessages(SimpleMessageCondition, MessageComparator)}
203 * .
204 * @param formatter
205 * Formatter to use to transform message into string.
206 * @return True if written, false otherwise.
207 */
208 boolean write(final OutputStream stream, final SimpleMessageCondition condition, final MessageComparator order,
209 final MessageFormatter formatter);
210
211 /**
212 * Will write to a stream the result of
213 * {@link #getMessages(SimpleMessageCondition)}, using given
214 * {@link MessageFormatter}. Will close the stream.
215 *
216 * @param stream
217 * Target.
218 * @param condition
219 * The condition to pass to
220 * {@link #getMessages(SimpleMessageCondition)}.
221 * @param formatter
222 * Formatter to use to transform message into string.
223 * @return True if written, false otherwise.
224 */
225 boolean write(final OutputStream stream, final SimpleMessageCondition condition, final MessageFormatter formatter);
226
227 }