1 /*
2 * Licensed under the Apache License, Version 2.0 (the "License");
3 * you may not use this file except in compliance with the License.
4 * You may obtain a copy of the License at
5 *
6 * http://www.apache.org/licenses/LICENSE-2.0
7 *
8 * Unless required by applicable law or agreed to in writing, software
9 * distributed under the License is distributed on an "AS IS" BASIS,
10 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 * See the License for the specific language governing permissions and
12 * limitations under the License.
13 *
14 */
15 package org.esigate.parser.future;
16
17 import java.io.IOException;
18 import java.util.concurrent.Future;
19 import java.util.concurrent.TimeUnit;
20 import java.util.concurrent.TimeoutException;
21
22 import org.esigate.HttpErrorPage;
23
24 /**
25 * This interface is similar to Appendable except that it is based on Future objects.
26 * <p>
27 * This allows to provide the content of the CharSequence to append at the very last moment, when all the CharSequences
28 * are effectively appended together.
29 * <p>
30 * While this interface allows concurrent implementation of an Appendable (based on Future), implementations are not
31 * required to be Thread-safe. This means that {@link #enqueueAppend(Future)}, {@link #performAppends()} and
32 * {@link #hasPending()} are supposed to be called for the same Thread.
33 * <p>
34 * Management of Threads concurrency must be implemented by the Future implementation which must perform all the
35 * synchronization work between any background Thread and the calling Thread.
36 *
37 * @author Nicolas Richeton
38 *
39 */
40 public interface FutureAppendable {
41
42 /**
43 * Queue the Future<CharSequence> for append in this <tt>FutureAppendable</tt>.
44 *
45 * <p>
46 * Caller may start computing the content of the Future parameter before or after calling this method (using other
47 * Thread) or simply wait for Future#get() to be called (deferred computation).
48 *
49 * @param csq
50 * The Future character sequence to append. If <tt>csq</tt> is <tt>null</tt>, then the four characters
51 * <tt>"null"</tt> are appended to this FutureAppendable.
52 *
53 * @return A reference to this <tt>FutureAppendable</tt>
54 *
55 * @throws IOException
56 * If an I/O error occurs
57 */
58 FutureAppendable enqueueAppend(Future<CharSequence> csq) throws IOException;
59
60 /**
61 * Wait for all computation to complete and perform the pending append operations.
62 *
63 * @return A reference to this <tt>FutureAppendable</tt>
64 * @throws IOException
65 * @throws HttpErrorPage
66 */
67 FutureAppendable performAppends() throws IOException, HttpErrorPage;
68
69 /**
70 *
71 * Wait for all computation to complete and perform the pending append operations.
72 *
73 * @param timeout
74 * @param unit
75 * @return FutureAppendable
76 * @throws IOException
77 * @throws HttpErrorPage
78 * @throws TimeoutException
79 */
80 FutureAppendable performAppends(int timeout, TimeUnit unit) throws IOException, HttpErrorPage, TimeoutException;
81
82 /**
83 * Check if some append operations are still waiting for {@link #performAppends()} to be called.
84 *
85 * @return true if append operations are pending.
86 */
87 boolean hasPending();
88
89 }