All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.facebook.presto.jdbc.internal.okio.Source Maven / Gradle / Ivy

There is a newer version: 0.289
Show newest version
/*
 * Copyright (C) 2014 Square, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.facebook.presto.jdbc.internal.okio;

import java.io.Closeable;
import java.io.IOException;

/**
 * Supplies a stream of bytes. Use this interface to read data from wherever
 * it's located: from the network, storage, or a buffer in memory. Sources may
 * be layered to transform supplied data, such as to decompress, decrypt, or
 * remove protocol framing.
 *
 * 

Most applications shouldn't operate on a source directly, but rather on a * {@link BufferedSource} which is both more efficient and more convenient. Use * {@link Okio#buffer(Source)} to wrap any source with a buffer. * *

Sources are easy to test: just use a {@link Buffer} in your tests, and * fill it with the data your application is to read. * *

Comparison with InputStream

* This interface is functionally equivalent to {@link java.io.InputStream}. * *

{@code InputStream} requires multiple layers when consumed data is * heterogeneous: a {@code DataInputStream} for primitive values, a {@code * BufferedInputStream} for buffering, and {@code InputStreamReader} for * strings. This class uses {@code BufferedSource} for all of the above. * *

Source avoids the impossible-to-implement {@linkplain * java.io.InputStream#available available()} method. Instead callers specify * how many bytes they {@link BufferedSource#require require}. * *

Source omits the unsafe-to-compose {@linkplain java.io.InputStream#mark * mark and reset} state that's tracked by {@code InputStream}; instead, callers * just buffer what they need. * *

When implementing a source, you don't need to worry about the {@linkplain * java.io.InputStream#read single-byte read} method that is awkward to implement efficiently * and returns one of 257 possible values. * *

And source has a stronger {@code skip} method: {@link BufferedSource#skip} * won't return prematurely. * *

Interop with InputStream

* Use {@link Okio#source} to adapt an {@code InputStream} to a source. Use * {@link BufferedSource#inputStream} to adapt a source to an {@code * InputStream}. */ public interface Source extends Closeable { /** * Removes at least 1, and up to {@code byteCount} bytes from this and appends * them to {@code sink}. Returns the number of bytes read, or -1 if this * source is exhausted. */ long read(Buffer sink, long byteCount) throws IOException; /** Returns the timeout for this source. */ Timeout timeout(); /** * Closes this source and releases the resources held by this source. It is an * error to read a closed source. It is safe to close a source more than once. */ @Override void close() throws IOException; }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy