001package ca.uhn.fhir.rest.client.api;
002
003/*
004 * #%L
005 * HAPI FHIR - Core Library
006 * %%
007 * Copyright (C) 2014 - 2019 University Health Network
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         * @deprecated This method was deprecated in HAPI FHIR 2.2 because its name has a typo. Use {@link #bufferEntity()} instead.
038         */
039        @Deprecated
040        void bufferEntitity() throws IOException;
041
042        /**
043         * Buffer the message entity data.
044         * <p>
045         * In case the message entity is backed by an unconsumed entity input stream,
046         * all the bytes of the original entity input stream are read and stored in a
047         * local buffer. The original entity input stream is consumed.
048         * </p>
049         * <p>
050         * In case the response entity instance is not backed by an unconsumed input stream
051         * an invocation of {@code bufferEntity} method is ignored and the method returns.
052         * </p>
053         * <p>
054         * This operation is idempotent, i.e. it can be invoked multiple times with
055         * the same effect which also means that calling the {@code bufferEntity()}
056         * method on an already buffered (and thus closed) message instance is legal
057         * and has no further effect.
058         * </p>
059         * <p>
060         * Buffering the message entity data allows for multiple invocations of
061         * {@code readEntity(...)} methods on the response instance.
062         *
063         * @since 2.2
064         */
065        void bufferEntity() throws IOException;
066
067        /**
068         * Close the response
069         */
070        void close();
071
072        /**
073         * Returns a reader for the response entity
074         */
075        Reader createReader() throws IOException;
076
077        /**
078         * Get map of the response headers and corresponding string values.
079         *
080         * @return response headers as a map header keys and they values.
081         */
082        Map<String, List<String>> getAllHeaders();
083
084        /**
085         * Return all headers in the response with the given type
086         */
087        List<String> getHeaders(String theName);
088
089        /**
090         * Extracts {@code Content-Type} value from the response exactly as
091         * specified by the {@code Content-Type} header. Returns {@code null}
092         * if not specified.
093         */
094        String getMimeType();
095
096        /**
097         * @return Returns a StopWatch that was started right before
098         * the client request was started. The time returned by this
099         * client includes any time that was spent within the HTTP
100         * library (possibly including waiting for a connection, and
101         * any network activity)
102         */
103        StopWatch getRequestStopWatch();
104
105        /**
106         * @return the native response, depending on the client library used
107         */
108        Object getResponse();
109
110        /**
111         * Get the status code associated with the response.
112         *
113         * @return the response status code.
114         */
115        int getStatus();
116
117        /**
118         * Get the response status information reason phrase associated with the response.
119         *
120         * @return the reason phrase.
121         */
122        String getStatusInfo();
123
124        /**
125         * Read the message entity input stream as an InputStream.
126         */
127        InputStream readEntity() throws IOException;
128}