001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 *  the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.http;
018
019import java.io.*;
020
021import org.apache.juneau.http.entity.*;
022import org.apache.juneau.http.part.*;
023
024/**
025 * Static factory methods for creating common HTTP body types.
026 *
027 * <p>
028 * Import statically for clean DSL-style usage:
029 * <p class='bjava'>
030 *    import static HttpBodies.*;
031 *
032 *    RestRequest <jv>req</jv> = client.post(<js>"/api/upload"</js>)
033 *       .body(stringBody(<js>"hello world"</js>, <js>"text/plain"</js>));
034 * </p>
035 *
036 * <h5 class='section'>See Also:</h5><ul>
037 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/NextGenRestClient">Next-Generation REST Client</a>
038 * </ul>
039 *
040 * @since 9.2.1
041 */
042public final class HttpBodies {
043
044   private HttpBodies() {}
045
046   /**
047    * Creates a UTF-8 {@code text/plain} body.
048    *
049    * @param content The string content. Must not be <jk>null</jk>.
050    * @return A new body. Never <jk>null</jk>.
051    */
052   public static StringBody stringBody(String content) {
053      return StringBody.of(content);
054   }
055
056   /**
057    * Creates a string body with a specific content type.
058    *
059    * @param content The string content. Must not be <jk>null</jk>.
060    * @param contentType The MIME content type. May be <jk>null</jk>.
061    * @return A new body. Never <jk>null</jk>.
062    */
063   public static StringBody stringBody(String content, String contentType) {
064      return StringBody.of(content, contentType);
065   }
066
067   /**
068    * Creates a body backed by a byte array.
069    *
070    * @param bytes The byte content. Must not be <jk>null</jk>.
071    * @return A new body. Never <jk>null</jk>.
072    */
073   public static ByteArrayBody byteArrayBody(byte[] bytes) {
074      return ByteArrayBody.of(bytes);
075   }
076
077   /**
078    * Creates a body backed by a byte array with a specific content type.
079    *
080    * @param bytes The byte content. Must not be <jk>null</jk>.
081    * @param contentType The MIME content type. May be <jk>null</jk>.
082    * @return A new body. Never <jk>null</jk>.
083    */
084   public static ByteArrayBody byteArrayBody(byte[] bytes, String contentType) {
085      return ByteArrayBody.of(bytes, contentType);
086   }
087
088   /**
089    * Creates a body backed by a file.
090    *
091    * @param file The file. Must not be <jk>null</jk>.
092    * @return A new body. Never <jk>null</jk>.
093    */
094   public static FileBody fileBody(File file) {
095      return FileBody.of(file);
096   }
097
098   /**
099    * Creates a body backed by a file with a specific content type.
100    *
101    * @param file The file. Must not be <jk>null</jk>.
102    * @param contentType The MIME content type. May be <jk>null</jk>.
103    * @return A new body. Never <jk>null</jk>.
104    */
105   public static FileBody fileBody(File file, String contentType) {
106      return FileBody.of(file, contentType);
107   }
108
109   /**
110    * Creates a streaming body backed by an {@link InputStream}.
111    *
112    * @param stream The input stream. Must not be <jk>null</jk>.
113    * @return A new body. Never <jk>null</jk>.
114    */
115   public static StreamBody streamBody(InputStream stream) {
116      return StreamBody.of(stream);
117   }
118
119   /**
120    * Creates a streaming body backed by an {@link InputStream} with a specific content type.
121    *
122    * @param stream The input stream. Must not be <jk>null</jk>.
123    * @param contentType The MIME content type. May be <jk>null</jk>.
124    * @return A new body. Never <jk>null</jk>.
125    */
126   public static StreamBody streamBody(InputStream stream, String contentType) {
127      return StreamBody.of(stream, contentType);
128   }
129
130   /**
131    * Creates a URL-encoded form body from the given parts.
132    *
133    * @param parts The form parts. Must not be <jk>null</jk>.
134    * @return A new body. Never <jk>null</jk>.
135    */
136   public static PartList formBody(HttpPart... parts) {
137      return PartList.of(parts);
138   }
139
140   /**
141    * Creates a URL-encoded form body from alternating name/value string pairs.
142    *
143    * @param pairs Alternating name/value strings. Must not be <jk>null</jk>. Length must be even.
144    * @return A new body. Never <jk>null</jk>.
145    */
146   public static PartList formBodyOfPairs(String... pairs) {
147      return PartList.ofPairs(pairs);
148   }
149}