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    * A creator for a part parser.
045    */
046   public static class Creator extends ContextBeanCreator<HttpPartParser> {
047      Creator() {
048         super(HttpPartParser.class);
049      }
050
051      Creator(Creator creator) {
052         super(creator);
053      }
054
055      /**
056       * Associates an existing bean context builder with this part parser.
057       *
058       * @param value The value for this setting.
059       * @return This object.
060       */
061      public Creator beanContext(BeanContext.Builder value) {
062         builder(BeanContextable.Builder.class).ifPresent(x -> x.beanContext(value));
063         return this;
064      }
065
066      @Override
067      public Creator copy() {
068         return new Creator(this);
069      }
070
071      @Override
072      public Creator impl(Object value) {
073         super.impl(value);
074         return this;
075      }
076
077      @Override
078      public Creator type(Class<? extends HttpPartParser> value) {
079         super.type(value);
080         return this;
081      }
082   }
083
084   /**
085    * Represent "no" part parser.
086    *
087    * <p>
088    * Used to represent the absence of a part parser in annotations.
089    */
090   public interface Void extends HttpPartParser {}
091
092   /**
093    * Instantiates a creator for a part parser.
094    * @return A new creator.
095    */
096   static Creator creator() {
097      return new Creator();
098   }
099
100   /**
101    * Returns metadata about the specified class.
102    *
103    * @param <T> The class type.
104    * @param c The class type.
105    * @return Metadata about the specified class.
106    */
107   <T> ClassMeta<T> getClassMeta(Class<T> c);
108
109   /**
110    * Returns metadata about the specified class.
111    *
112    * @param <T> The class type.
113    * @param t The class type.
114    * @param args The class type args.
115    * @return Metadata about the specified class.
116    */
117   <T> ClassMeta<T> getClassMeta(Type t, Type...args);
118
119   /**
120    * Creates a new parser session.
121    *
122    * @return A new parser session.
123    */
124   HttpPartParserSession getPartSession();
125}