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