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