Package: InputSource

InputSource

Coverage

1: /*
2: * Copyright (c) 2010, 2020 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0, which is available at
6: * http://www.eclipse.org/legal/epl-2.0.
7: *
8: * This Source Code may also be made available under the following Secondary
9: * Licenses when the conditions for such availability set forth in the
10: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11: * version 2 with the GNU Classpath Exception, which is available at
12: * https://www.gnu.org/software/classpath/license.html.
13: *
14: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15: */
16:
17: package org.glassfish.grizzly;
18:
19: import java.io.InputStream;
20: import java.io.Reader;
21:
22: /**
23: * <p>
24: * This interface defines methods to allow an {@link InputStream} or {@link Reader} to notify the developer
25: * <em>when</em> and <em>how much</em> data is ready to be read without blocking.
26: * </p>
27: *
28: * @since 2.0
29: */
30: public interface InputSource {
31:
32: /**
33: * <p>
34: * Notify the specified {@link ReadHandler} when any number of bytes or characters can be read without blocking.
35: * </p>
36: *
37: * <p>
38: * Invoking this method is equivalent to calling: notifyAvailable(handler, 1).
39: * </p>
40: *
41: * @param handler the {@link ReadHandler} to notify.
42: *
43: * @throws IllegalArgumentException if <code>handler</code> is <code>null</code>.
44: * @throws IllegalStateException if an attempt is made to register a handler before an existing registered handler has
45: * been invoked or if all request data has already been read.
46: *
47: * @see ReadHandler#onDataAvailable()
48: * @see ReadHandler#onAllDataRead()
49: */
50: void notifyAvailable(final ReadHandler handler);
51:
52: /**
53: * <p>
54: * Notify the specified {@link ReadHandler} when the number of bytes that can be read without blocking is greater or
55: * equal to the specified <code>size</code>.
56: * </p>
57: *
58: * @param handler the {@link ReadHandler} to notify.
59: * @param size the least number of bytes that must be available before the {@link ReadHandler} is invoked.
60: *
61: * @throws IllegalArgumentException if <code>handler</code> is <code>null</code>, or if <code>size</code> is less or
62: * equal to zero.
63: * @throws IllegalStateException if an attempt is made to register a handler before an existing registered handler has
64: * been invoked or if all request data has already been read.
65: *
66: * @see ReadHandler#onDataAvailable()
67: * @see ReadHandler#onAllDataRead()
68: */
69: void notifyAvailable(final ReadHandler handler, final int size);
70:
71: /**
72: * @return <code>true</code> when all data for this particular request has been read, otherwise returns
73: * <code>false</code>.
74: */
75: boolean isFinished();
76:
77: /**
78: * @return the number of bytes (or characters) that may be obtained without blocking. Note when dealing with characters,
79: * this method may return an estimate on the number of characters available.
80: */
81: int readyData();
82:
83: /**
84: * @return <code>true</code> if data can be obtained without blocking, otherwise returns <code>false</code>.
85: */
86: boolean isReady();
87:
88: }