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.marshall.httppart;
018
019import java.lang.reflect.*;
020
021import org.apache.juneau.marshall.*;
022import org.apache.juneau.marshall.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.marshall.oapi.OpenApiParser} - Parts encoded in based on OpenAPI schema.
031 *    <li class='jc'>{@link org.apache.juneau.marshall.uon.UonParser} - Parts encoded in UON notation.
032 *    <li class='jc'>{@link 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 */
042@SuppressWarnings({
043   "java:S9398" // Nested type is public API; moving it would break callers.
044})
045public interface HttpPartParser {
046
047   /**
048    * A creator for a part parser.
049    */
050   public static class Creator extends ContextBeanCreator<HttpPartParser> {
051      Creator() {
052         super(HttpPartParser.class);
053      }
054
055      Creator(Creator creator) {
056         super(creator);
057      }
058
059      /**
060       * Associates an existing bean context builder with this part parser.
061       *
062       * @param value The value for this setting.
063       * @return This object.
064       */
065      public Creator marshallingContext(MarshallingContext.Builder value) {
066         builder(MarshallingContextable.Builder.class).ifPresent(x -> x.marshallingContext(value));
067         return this;
068      }
069
070      @Override
071      public Creator copy() {
072         return new Creator(this);
073      }
074
075      @Override
076      public Creator impl(Object value) {
077         super.impl(value);
078         return this;
079      }
080
081      @Override
082      public Creator type(Class<? extends HttpPartParser> value) {
083         super.type(value);
084         return this;
085      }
086   }
087
088   /**
089    * Represent "no" part parser.
090    *
091    * <p>
092    * Used to represent the absence of a part parser in annotations.
093    */
094   @SuppressWarnings({
095      "java:S9398" // Public annotation-default marker; moving breaks API.
096   })
097   public interface Void extends HttpPartParser {}
098
099   /**
100    * Instantiates a creator for a part parser.
101    * @return A new creator.
102    */
103   static Creator creator() {
104      return new Creator();
105   }
106
107   /**
108    * Returns metadata about the specified class.
109    *
110    * @param <T> The class type.
111    * @param c The class type.
112    * @return Metadata about the specified class.
113    */
114   <T> ClassMeta<T> getClassMeta(Class<T> c);
115
116   /**
117    * Returns metadata about the specified class.
118    *
119    * @param <T> The class type.
120    * @param t The class type.
121    * @param args The class type args.
122    * @return Metadata about the specified class.
123    */
124   <T> ClassMeta<T> getClassMeta(Type t, Type...args);
125
126   /**
127    * Creates a new parser session.
128    *
129    * @return A new parser session.
130    */
131   HttpPartParserSession getPartSession();
132}