001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  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 distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.httppart;
014
015import java.lang.reflect.*;
016
017import org.apache.juneau.*;
018import org.apache.juneau.parser.*;
019
020/**
021 * Session object that lives for the duration of a single use of {@link HttpPartParser}.
022 *
023 * <p>
024 * This class is NOT thread safe.
025 * It is typically discarded after one-time use although it can be reused within the same thread.
026 */
027public interface HttpPartParserSession {
028
029   /**
030    * Converts the specified input to the specified class type.
031    *
032    * @param partType The part type being parsed.
033    * @param schema
034    *    Schema information about the part.
035    *    <br>May be <jk>null</jk>.
036    *    <br>Not all part parsers use the schema information.
037    * @param in The input being parsed.
038    * @param toType The POJO type to transform the input into.
039    * @return The parsed value.
040    * @throws ParseException Malformed input encountered.
041    * @throws SchemaValidationException If the input or resulting HTTP part object fails schema validation.
042    */
043   public <T> T parse(HttpPartType partType, HttpPartSchema schema, String in, ClassMeta<T> toType) throws ParseException, SchemaValidationException;
044
045   /**
046    * Converts the specified input to the specified class type.
047    *
048    * @param partType The part type being parsed.
049    * @param schema
050    *    Schema information about the part.
051    *    <br>May be <jk>null</jk>.
052    *    <br>Not all part parsers use the schema information.
053    * @param in The input being parsed.
054    * @param toType The POJO type to transform the input into.
055    * @return The parsed value.
056    * @throws ParseException Malformed input encountered.
057    * @throws SchemaValidationException If the input or resulting HTTP part object fails schema validation.
058    */
059   public <T> T parse(HttpPartType partType, HttpPartSchema schema, String in, Class<T> toType) throws ParseException, SchemaValidationException;
060
061   /**
062    * Converts the specified input to the specified class type.
063    *
064    * @param partType The part type being parsed.
065    * @param schema
066    *    Schema information about the part.
067    *    <br>May be <jk>null</jk>.
068    *    <br>Not all part parsers use the schema information.
069    * @param in The input being parsed.
070    * @param toType The POJO type to transform the input into.
071    * @param toTypeArgs The POJO type arguments for Collection and Map types.
072    * @return The parsed value.
073    * @throws ParseException Malformed input encountered.
074    * @throws SchemaValidationException If the input or resulting HTTP part object fails schema validation.
075    */
076   public <T> T parse(HttpPartType partType, HttpPartSchema schema, String in, Type toType, Type...toTypeArgs) throws ParseException, SchemaValidationException;
077
078   /**
079    * Same as {@link #parse(HttpPartType, HttpPartSchema, String, ClassMeta)} but defaults to a <jk>null</jk> part type.
080    *
081    * @param schema
082    *    Schema information about the part.
083    *    <br>May be <jk>null</jk>.
084    *    <br>Not all part parsers use the schema information.
085    * @param in The input being parsed.
086    * @param toType The POJO type to transform the input into.
087    * @return The parsed value.
088    * @throws ParseException Malformed input encountered.
089    * @throws SchemaValidationException If the input or resulting HTTP part object fails schema validation.
090    */
091   public <T> T parse(HttpPartSchema schema, String in, ClassMeta<T> toType) throws ParseException, SchemaValidationException;
092
093   /**
094    * Same as {@link #parse(HttpPartType, HttpPartSchema, String, Class)} but defaults to a <jk>null</jk> part type.
095    *
096    * @param schema
097    *    Schema information about the part.
098    *    <br>May be <jk>null</jk>.
099    *    <br>Not all part parsers use the schema information.
100    * @param in The input being parsed.
101    * @param toType The POJO type to transform the input into.
102    * @return The parsed value.
103    * @throws ParseException Malformed input encountered.
104    * @throws SchemaValidationException If the input or resulting HTTP part object fails schema validation.
105    */
106   public <T> T parse(HttpPartSchema schema, String in, Class<T> toType) throws ParseException, SchemaValidationException;
107
108   /**
109    * Same as {@link #parse(HttpPartType, HttpPartSchema, String, Type, Type...)} but defaults to a <jk>null</jk> part type.
110    *
111    * @param schema
112    *    Schema information about the part.
113    *    <br>May be <jk>null</jk>.
114    *    <br>Not all part parsers use the schema information.
115    * @param in The input being parsed.
116    * @param toType The POJO type to transform the input into.
117    * @param toTypeArgs The POJO type arguments for Collection and Map types.
118    * @return The parsed value.
119    * @throws ParseException Malformed input encountered.
120    * @throws SchemaValidationException If the input or resulting HTTP part object fails schema validation.
121    */
122   public <T> T parse(HttpPartSchema schema, String in, Type toType, Type...toTypeArgs) throws ParseException, SchemaValidationException;
123}