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    * A creator for a part serializer.
057    */
058   public static class Creator extends ContextBeanCreator<HttpPartSerializer> {
059
060      Creator() {
061         super(HttpPartSerializer.class);
062      }
063
064      Creator(Creator builder) {
065         super(builder);
066      }
067
068      /**
069       * Associates an existing bean context builder with this part serializer.
070       *
071       * @param value The value for this setting.
072       * @return This object.
073       */
074      public Creator beanContext(BeanContext.Builder value) {
075         builder(BeanContextable.Builder.class).ifPresent(x -> x.beanContext(value));
076         return this;
077      }
078
079      @Override
080      public Creator copy() {
081         return new Creator(this);
082      }
083
084      @Override
085      public Creator impl(Object value) {
086         super.impl(value);
087         return this;
088      }
089
090      @Override
091      public Creator type(Class<? extends HttpPartSerializer> value) {
092         super.type(value);
093         return this;
094      }
095   }
096
097   /**
098    * Represent "no" part part serializer.
099    *
100    * <p>
101    * Used to represent the absence of a part serializer in annotations.
102    */
103   public interface Void extends HttpPartSerializer {}
104
105   /**
106    * Instantiates a creator for a part serializer.
107    * @return A new creator.
108    */
109   static Creator creator() {
110      return new Creator();
111   }
112
113   /**
114    * Creates a new serializer session.
115    *
116    * @return A new serializer session.
117    */
118   HttpPartSerializerSession getPartSession();
119}