001package ca.uhn.fhir.rest.client.api;
002
003/*
004 * #%L
005 * HAPI FHIR - Core Library
006 * %%
007 * Copyright (C) 2014 - 2023 Smile CDR, Inc.
008 * %%
009 * Licensed under the Apache License, Version 2.0 (the "License");
010 * you may not use this file except in compliance with the License.
011 * You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing, software
016 * distributed under the License is distributed on an "AS IS" BASIS,
017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018 * See the License for the specific language governing permissions and
019 * limitations under the License.
020 * #L%
021 */
022
023import ca.uhn.fhir.util.StopWatch;
024
025import java.io.IOException;
026import java.io.InputStream;
027import java.io.Reader;
028import java.util.List;
029import java.util.Map;
030
031/**
032 * An interface around the HTTP Response.
033 */
034public interface IHttpResponse {
035
036        /**
037         * Buffer the message entity data.
038         * <p>
039         * In case the message entity is backed by an unconsumed entity input stream,
040         * all the bytes of the original entity input stream are read and stored in a
041         * local buffer. The original entity input stream is consumed.
042         * </p>
043         * <p>
044         * In case the response entity instance is not backed by an unconsumed input stream
045         * an invocation of {@code bufferEntity} method is ignored and the method returns.
046         * </p>
047         * <p>
048         * This operation is idempotent, i.e. it can be invoked multiple times with
049         * the same effect which also means that calling the {@code bufferEntity()}
050         * method on an already buffered (and thus closed) message instance is legal
051         * and has no further effect.
052         * </p>
053         * <p>
054         * Buffering the message entity data allows for multiple invocations of
055         * {@code readEntity(...)} methods on the response instance.
056         *
057         * @since 2.2
058         */
059        void bufferEntity() throws IOException;
060
061        /**
062         * Close the response
063         */
064        void close();
065
066        /**
067         * Returns a reader for the response entity
068         */
069        Reader createReader() throws IOException;
070
071        /**
072         * Get map of the response headers and corresponding string values.
073         *
074         * @return response headers as a map header keys and they values.
075         */
076        Map<String, List<String>> getAllHeaders();
077
078        /**
079         * Return all headers in the response with the given type
080         */
081        List<String> getHeaders(String theName);
082
083        /**
084         * Extracts {@code Content-Type} value from the response exactly as
085         * specified by the {@code Content-Type} header. Returns {@code null}
086         * if not specified.
087         */
088        String getMimeType();
089
090        /**
091         * @return Returns a StopWatch that was started right before
092         * the client request was started. The time returned by this
093         * client includes any time that was spent within the HTTP
094         * library (possibly including waiting for a connection, and
095         * any network activity)
096         */
097        StopWatch getRequestStopWatch();
098
099        /**
100         * @return the native response, depending on the client library used
101         */
102        Object getResponse();
103
104        /**
105         * Get the status code associated with the response.
106         *
107         * @return the response status code.
108         */
109        int getStatus();
110
111        /**
112         * Get the response status information reason phrase associated with the response.
113         *
114         * @return the reason phrase.
115         */
116        String getStatusInfo();
117
118        /**
119         * Read the message entity input stream as an InputStream.
120         */
121        InputStream readEntity() throws IOException;
122}