com.spotify.docker.client.LogStream Maven / Gradle / Ivy
/*-
* -\-\-
* docker-client
* --
* Copyright (C) 2016 Spotify AB
* --
* 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.spotify.docker.client;
import java.io.Closeable;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Iterator;
public interface LogStream extends Iterator, Closeable {
String readFully();
/**
* Attaches two {@link java.io.OutputStream}s to the {@link LogStream}. Closes the streams after
* use.
*
* @param stdout OutputStream for the standard out
* @param stderr OutputStream for the standard err
* @throws IOException if an I/O error occurs
* @see #attach(OutputStream, OutputStream, boolean) for control over stream lifecycles
*/
void attach(OutputStream stdout, OutputStream stderr) throws IOException;
/**
* Attaches two {@link java.io.OutputStream}s to the {@link LogStream}.
*
* Example usage:
*
*
* {@code
* dockerClient
* .attachContainer(containerId,
* AttachParameter.LOGS, AttachParameter.STDOUT,
* AttachParameter.STDERR, AttachParameter.STREAM)
* .attach(System.out, System.err);
* }
*
*
* Typically you use {@link java.io.PipedOutputStream} connected to a {@link
* java.io.PipedInputStream} which are read by - for example - an {@link
* java.io.InputStreamReader} or a {@link java.util.Scanner}. For small inputs, the {@link
* java.io.PipedOutputStream} just writes to the buffer of the {@link java.io.PipedInputStream},
* but you actually want to read and write from separate threads, as it may deadlock the thread.
*
*
*
* {@code
* final PipedInputStream stdout = new PipedInputStream();
* final PipedInputStream stderr = new PipedInputStream();
* final PipedOutputStream stdout_pipe = new PipedOutputStream(stdout);
* final PipedOutputStream stderr_pipe = new PipedOutputStream(stderr);
*
* executor.submit(new Callable<Void>() {
* @Override
* public Void call() throws Exception {
* dockerClient.attachContainer(containerId,
* AttachParameter.LOGS, AttachParameter.STDOUT,
* AttachParameter.STDERR, AttachParameter.STREAM
* .attach(stdout_pipe, stderr_pipe);
* return null;
* }
* });
*
* try (Scanner sc_stdout = new Scanner(stdout); Scanner sc_stderr = new Scanner(stderr)) {
* // ... read here
* }
* }
*
*
* @param stdout OutputStream for the standard out
* @param stderr OutputStream for the standard err
* @param closeAtEof whether to close the streams when this log stream ends
* @throws IOException if an I/O error occurs
* @see java.io.PipedInputStream
* @see java.io.PipedOutputStream
*/
void attach(OutputStream stdout, OutputStream stderr, boolean closeAtEof) throws IOException;
/**
* Redefine to not throw checked exceptions.
*/
void close();
}