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