001// Copyright 2019 Google LLC
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//      http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package com.google.cloud.functions;
016
017import java.io.BufferedReader;
018import java.io.IOException;
019import java.io.InputStream;
020import java.util.List;
021import java.util.Map;
022import java.util.Optional;
023
024/**
025 * Represents an HTTP message, either an HTTP request or a part of a multipart HTTP request.
026 */
027public interface HttpMessage {
028  /**
029   * Returns the value of the {@code Content-Type} header, if any.
030   *
031   * @return the content type, if any.
032   */
033  Optional<String> getContentType();
034
035  /**
036   * Returns the numeric value of the {@code Content-Length} header.
037   *
038   * @return the content length.
039   */
040  long getContentLength();
041
042  /**
043   * Returns the character encoding specified in the {@code Content-Type} header,
044   * or {@code Optional.empty()} if there is no {@code Content-Type} header or it does not have the
045   * {@code charset} parameter.
046   *
047   * @return the character encoding for the content type, if one is specified.
048   */
049  Optional<String> getCharacterEncoding();
050
051  /**
052   * Returns an {@link InputStream} that can be used to read the body of this HTTP request.
053   * Every call to this method on the same {@link HttpMessage} will return the same object.
054   * This method is typically used to read binary data. If the body is text, the
055   * {@link #getReader()} method is more appropriate.
056   *
057   * @return an {@link InputStream} that can be used to read the body of this HTTP request.
058   * @throws IOException if a valid {@link InputStream} cannot be returned for some reason.
059   * @throws IllegalStateException if {@link #getReader()} has already been called on this instance.
060   */
061  InputStream getInputStream() throws IOException;
062
063  /**
064   * Returns a {@link BufferedReader} that can be used to read the text body of this HTTP request.
065   * Every call to this method on the same {@link HttpMessage} will return the same object.
066   *
067   * @return a {@link BufferedReader} that can be used to read the text body of this HTTP request.
068   * @throws IOException if a valid {@link BufferedReader} cannot be returned for some reason.
069   * @throws IllegalStateException if {@link #getInputStream()} has already been called on this
070   *     instance.
071   */
072  BufferedReader getReader() throws IOException;
073
074  /**
075   * Returns a map describing the headers of this HTTP request, or this part of a multipart
076   * request. If the headers look like this...
077   *
078   * <pre>
079   *   Content-Type: text/plain
080   *   Some-Header: some value
081   *   Some-Header: another value
082   * </pre>
083   *
084   * ...then the returned value will map {@code "Content-Type"} to a one-element list containing
085   * {@code "text/plain"}, and {@code "Some-Header"} to a two-element list containing
086   * {@code "some value"} and {@code "another value"}.
087   *
088   * @return a map where each key is an HTTP header and the corresponding {@code List} value has
089   *     one element for each occurrence of that header.
090   */
091  Map<String, List<String>> getHeaders();
092
093  /**
094   * Convenience method that returns the value of the first header with the given name. If the
095   * headers look like this...
096   *
097   * <pre>
098   *   Content-Type: text/plain
099   *   Some-Header: some value
100   *   Some-Header: another value
101   * </pre>
102   *
103   * ...then {@code getFirstHeader("Some-Header")} will return {@code Optional.of("some value")},
104   * and {@code getFirstHeader("Another-Header")} will return {@code Optional.empty()}.
105   *
106   * @param name an HTTP header name.
107   *
108   * @return the first value of the given header, if present.
109   */
110  default Optional<String> getFirstHeader(String name) {
111    List<String> headers = getHeaders().get(name);
112    if (headers == null || headers.isEmpty()) {
113      return Optional.empty();
114    }
115    return Optional.of(headers.get(0));
116  }
117}