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.httppart;
018
019import java.lang.reflect.*;
020
021import org.apache.juneau.*;
022import org.apache.juneau.cp.*;
023
024/**
025 * Interface used to convert HTTP headers, query parameters, form-data parameters, and URI path variables to POJOs
026 *
027 * <p>
028 * The following default implementations are provided:
029 * <ul class='doctree'>
030 *    <li class='jc'>{@link org.apache.juneau.oapi.OpenApiParser} - Parts encoded in based on OpenAPI schema.
031 *    <li class='jc'>{@link org.apache.juneau.uon.UonParser} - Parts encoded in UON notation.
032 *    <li class='jc'>{@link org.apache.juneau.httppart.SimplePartParser} - Parts encoded in plain text.
033 * </ul>
034 *
035 * <p>
036 * Implementations must include either a public no-args constructor.
037 *
038 * <h5 class='section'>See Also:</h5><ul>
039 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HttpPartSerializersParsers">HTTP Part Serializers and Parsers</a>
040 * </ul>
041 */
042public interface HttpPartParser {
043
044   //-----------------------------------------------------------------------------------------------------------------
045   // Static
046   //-----------------------------------------------------------------------------------------------------------------
047
048   /**
049    * Represent "no" part parser.
050    *
051    * <p>
052    * Used to represent the absence of a part parser in annotations.
053    */
054   public interface Void extends HttpPartParser {}
055
056   /**
057    * Instantiates a creator for a part parser.
058    * @return A new creator.
059    */
060   static Creator creator() {
061      return new Creator();
062   }
063
064   //-----------------------------------------------------------------------------------------------------------------
065   // Creator
066   //-----------------------------------------------------------------------------------------------------------------
067
068   /**
069    * A creator for a part parser.
070    */
071   public static class Creator extends ContextBeanCreator<HttpPartParser> {
072      Creator() {
073         super(HttpPartParser.class);
074      }
075
076      Creator(Creator creator) {
077         super(creator);
078      }
079
080      @Override
081      public Creator impl(Object value) {
082         super.impl(value);
083         return this;
084      }
085
086      @Override
087      public Creator type(Class<? extends HttpPartParser> value) {
088         super.type(value);
089         return this;
090      }
091
092      @Override
093      public Creator copy() {
094         return new Creator(this);
095      }
096
097      /**
098       * Associates an existing bean context builder with this part parser.
099       *
100       * @param value The value for this setting.
101       * @return This object.
102       */
103      public Creator beanContext(BeanContext.Builder value) {
104         builder(BeanContextable.Builder.class).ifPresent(x -> x.beanContext(value));
105         return this;
106      }
107   }
108
109   //-----------------------------------------------------------------------------------------------------------------
110   // Instance
111   //-----------------------------------------------------------------------------------------------------------------
112
113   /**
114    * Creates a new parser session.
115    *
116    * @return A new parser session.
117    */
118   HttpPartParserSession getPartSession();
119
120   /**
121    * Returns metadata about the specified class.
122    *
123    * @param <T> The class type.
124    * @param c The class type.
125    * @return Metadata about the specified class.
126    */
127   <T> ClassMeta<T> getClassMeta(Class<T> c);
128
129   /**
130    * Returns metadata about the specified class.
131    *
132    * @param <T> The class type.
133    * @param t The class type.
134    * @param args The class type args.
135    * @return Metadata about the specified class.
136    */
137   <T> ClassMeta<T> getClassMeta(Type t, Type...args);
138}