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