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