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.*;
020import java.util.function.*;
021
022import org.apache.juneau.http.entity.*;
023import org.apache.juneau.http.header.*;
024import org.apache.juneau.httppart.*;
025import org.apache.juneau.serializer.*;
026
027/**
028 * Standard predefined HTTP entities.
029 *
030 * <h5 class='section'>See Also:</h5><ul>
031 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
032 * </ul>
033 */
034public class HttpEntities {
035
036   /**
037    * Creates a new {@link ByteArrayEntity} builder.
038    *
039    * <p>
040    * Assumes no content type.
041    *
042    * @param content The entity content.  Can be <jk>null</jk>.
043    * @return A new {@link ByteArrayEntity} builder.
044    */
045   public static final ByteArrayEntity byteArrayEntity(byte[] content) {
046      return new ByteArrayEntity().setContent(content);
047   }
048
049   /**
050    * Creates a new {@link ByteArrayEntity} builder.
051    *
052    * @param content The entity content.  Can be <jk>null</jk>.
053    * @param contentType The entity content type, or <jk>null</jk> if not specified.
054    * @return A new {@link ByteArrayEntity} builder.
055    */
056   public static final ByteArrayEntity byteArrayEntity(byte[] content, ContentType contentType) {
057      return new ByteArrayEntity().setContent(content).setContentType(contentType);
058   }
059
060   /**
061    * Creates a new {@link ByteArrayEntity} builder.
062    *
063    * <p>
064    * Assumes no content type.
065    *
066    * @param content The entity content supplier.  Can be <jk>null</jk>.
067    * @return A new {@link ByteArrayEntity} builder.
068    */
069   public static final ByteArrayEntity byteArrayEntity(Supplier<byte[]> content) {
070      return new ByteArrayEntity().setContent(content);
071   }
072
073   /**
074    * Creates a new {@link ByteArrayEntity} builder.
075    *
076    * @param content The entity content supplier.  Can be <jk>null</jk>.
077    * @param contentType The entity content type, or <jk>null</jk> if not specified.
078    * @return A new {@link ByteArrayEntity} builder.
079    */
080   public static final ByteArrayEntity byteArrayEntity(Supplier<byte[]> content, ContentType contentType) {
081      return new ByteArrayEntity().setContent(content).setContentType(contentType);
082   }
083
084   /**
085    * Creates a new {@link FileEntity} builder.
086    *
087    * <p>
088    * Assumes no content type.
089    *
090    * @param content The entity content.  Can be <jk>null</jk>.
091    * @return A new {@link FileEntity} builder.
092    */
093   public static final FileEntity fileEntity(File content) {
094      return new FileEntity().setContent(content);
095   }
096
097   /**
098    * Creates a new {@link FileEntity} builder.
099    *
100    * @param content The entity content.  Can be <jk>null</jk>.
101    * @param contentType The entity content type, or <jk>null</jk> if not specified.
102    * @return A new {@link FileEntity} builder.
103    */
104   public static final FileEntity fileEntity(File content, ContentType contentType) {
105      return new FileEntity().setContent(content).setContentType(contentType);
106   }
107
108   /**
109    * Creates a new {@link ReaderEntity} builder.
110    *
111    * @param content The entity content.  Can be <jk>null</jk>.
112    * @return A new {@link ReaderEntity} builder.
113    */
114   public static final ReaderEntity readerEntity(Reader content) {
115      return new ReaderEntity().setContent(content);
116   }
117
118   /**
119    * Creates a new {@link ReaderEntity} builder.
120    *
121    * @param content The entity content.  Can be <jk>null</jk>.
122    * @param contentType The entity content type, or <jk>null</jk> if not specified.
123    * @return A new {@link ReaderEntity} builder.
124    */
125   public static final ReaderEntity readerEntity(Reader content, ContentType contentType) {
126      return new ReaderEntity().setContent(content).setContentType(contentType);
127   }
128
129   /**
130    * Creates a new {@link SerializedEntity} object.
131    *
132    * @param content
133    *    The Java POJO representing the content.
134    *    <br>Can be <jk>null</jk>.
135    * @param serializer
136    *    The serializer to use to serialize the POJO.
137    *    <br>If <jk>null</jk>, POJO will be converted to a string using {@link Object#toString()}.
138    * @return A new {@link SerializedEntity} object.
139    */
140   public static final SerializedEntity serializedEntity(Object content, Serializer serializer) {
141      return new SerializedEntity().setContent(content).setSerializer(serializer);
142   }
143
144   /**
145    * Creates a new {@link SerializedEntity} object.
146    *
147    * @param content
148    *    The supplier of a Java POJO representing the content.
149    *    <br>Can be <jk>null</jk>.
150    * @param serializer
151    *    The serializer to use to serialize the POJO.
152    *    <br>If <jk>null</jk>, POJO will be converted to a string using {@link Object#toString()}.
153    * @return A new {@link SerializedEntity} object.
154    */
155   public static final SerializedEntity serializedEntity(Supplier<?> content, Serializer serializer) {
156      return new SerializedEntity().setContent(content).setSerializer(serializer);
157   }
158
159   /**
160    * Creates a new {@link SerializedEntity} object.
161    *
162    * @param content
163    *    The Java POJO representing the content.
164    *    <br>Can be <jk>null</jk>.
165    * @param serializer
166    *    The serializer to use to serialize the POJO.
167    *    <br>If <jk>null</jk>, POJO will be converted to a string using {@link Object#toString()}.
168    * @param schema
169    *    Optional HTTP-part schema for providing instructionst to the serializer on the format of the entity.
170    * @return A new {@link SerializedEntity} object.
171    */
172   public static final SerializedEntity serializedEntity(Object content, Serializer serializer, HttpPartSchema schema) {
173      return new SerializedEntity().setContent(content).setSerializer(serializer).setSchema(schema);
174   }
175
176   /**
177    * Creates a new {@link SerializedEntity} object.
178    *
179    * @param content
180    *    The supplier of a Java POJO representing the content.
181    *    <br>Can be <jk>null</jk>.
182    * @param serializer
183    *    The serializer to use to serialize the POJO.
184    *    <br>If <jk>null</jk>, POJO will be converted to a string using {@link Object#toString()}.
185    * @param schema
186    *    Optional HTTP-part schema for providing instructionst to the serializer on the format of the entity.
187    * @return A new {@link SerializedEntity} object.
188    */
189   public static final SerializedEntity serializedEntity(Supplier<?> content, Serializer serializer, HttpPartSchema schema) {
190      return new SerializedEntity().setContent(content).setSerializer(serializer).setSchema(schema);
191   }
192
193   /**
194    * Creates a new {@link StreamEntity} builder.
195    *
196    * <p>
197    * Assumes no content type.
198    *
199    * @param content The entity content.  Can be <jk>null</jk>.
200    * @return A new {@link StreamEntity} builder.
201    */
202   public static final StreamEntity streamEntity(InputStream content) {
203      return new StreamEntity().setContent(content);
204   }
205
206   /**
207    * Creates a new {@link StreamEntity} builder.
208    *
209    * @param content The entity content.  Can be <jk>null</jk>.
210    * @param contentType The entity content type, or <jk>null</jk> if not specified.
211    * @param length The content length, or <c>-1</c> if not known.
212    * @return A new {@link StreamEntity} builder.
213    */
214   public static final StreamEntity streamEntity(InputStream content, long length, ContentType contentType) {
215      return new StreamEntity().setContent(content).setContentLength(length).setContentType(contentType);
216   }
217
218   /**
219    * Creates a new builder for a {@link StringEntity} builder.
220    *
221    * @param content The entity content.  Can be <jk>null</jk>.
222    * @return A new {@link StringEntity} builder.
223    */
224   public static final StringEntity stringEntity(String content) {
225      return new StringEntity().setContent(content);
226   }
227
228   /**
229    * Creates a new builder for a {@link StringEntity} builder.
230    *
231    * @param content The entity content.  Can be <jk>null</jk>.
232    * @param contentType The entity content type, or <jk>null</jk> if not specified.
233    * @return A new {@link StringEntity} builder.
234    */
235   public static final StringEntity stringEntity(String content, ContentType contentType) {
236      return new StringEntity().setContent(content).setContentType(contentType);
237   }
238
239   /**
240    * Creates a new builder for a {@link StringEntity} builder.
241    *
242    * @param content The entity content.  Can be <jk>null</jk>.
243    * @return A new {@link StringEntity} builder.
244    */
245   public static final StringEntity stringEntity(Supplier<String> content) {
246      return new StringEntity().setContent(content);
247   }
248
249   /**
250    * Creates a new builder for a {@link StringEntity} builder.
251    *
252    * @param content The entity content.  Can be <jk>null</jk>.
253    * @param contentType The entity content type, or <jk>null</jk> if not specified.
254    * @return A new {@link StringEntity} builder.
255    */
256   public static final StringEntity stringEntity(Supplier<String> content, ContentType contentType) {
257      return new StringEntity().setContent(content).setContentType(contentType);
258   }
259}