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
019
020import org.apache.juneau.commons.httppart.*;
021import org.apache.juneau.marshall.*;
022import org.apache.juneau.marshall.serializer.*;
023import static org.apache.juneau.commons.utils.Shorts.*;
024
025/**
026 * Base class for implementations of {@link HttpPartSerializer}
027 *
028 * <h5 class='section'>Notes:</h5><ul>
029 *    <li class='note'>This class is thread safe and reusable.
030 * </ul>
031 *
032 * <h5 class='section'>See Also:</h5><ul>
033 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HttpPartSerializersParsers">HTTP Part Serializers and Parsers</a>
034 * </ul>
035 */
036@SuppressWarnings({
037   "java:S1192" // Duplicated literals (argument/property names) read more clearly inline than as constants
038})
039public abstract class BaseHttpPartSerializer extends MarshallingContextable implements HttpPartSerializer {
040
041   /**
042    * Builder class.
043    */
044   @SuppressWarnings({
045      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
046   })
047   public abstract static class Builder<SELF extends Builder<SELF>> extends MarshallingContextable.Builder<SELF> {
048
049      /**
050       * Constructor.
051       */
052      protected Builder() {}
053
054      /**
055       * Copy constructor.
056       * @param builder The existing builder to copy.
057       *    <br>Cannot be <jk>null</jk>.
058       */
059      protected Builder(Builder<SELF> builder) {
060         super(reqnn("builder", builder));
061      }
062   }
063
064   /**
065    * Constructor.
066    *
067    * @param builder The builder for this object.
068    */
069   protected BaseHttpPartSerializer(Builder<?> builder) {
070      super(builder);
071   }
072
073   /**
074    * Converts the specified value to a string that can be used as an HTTP header value, query parameter value,
075    * form-data parameter, or URI path variable.
076    *
077    * <p>
078    * Returned values should NOT be URL-encoded.
079    *
080    * @param partType The category of value being serialized.
081    *    <br>Can be <jk>null</jk> (will default to {@link HttpPartType#OTHER}).
082    * @param schema
083    *    Schema information about the part.
084    *    <br>Can be <jk>null</jk>.  The effect is implementation-dependent — see {@link HttpPartSerializerSession}.
085    *    <br>Not all part serializers use the schema information.
086    * @param value The value being serialized.
087    *    <br>Can be <jk>null</jk> (will return <jk>null</jk>).
088    * @return The serialized value.
089    * @throws SerializeException If a problem occurred while trying to parse the input.
090    * @throws SchemaValidationException If the output fails schema validation.
091    */
092   public String write(HttpPartType partType, HttpPartSchema schema, Object value) throws SchemaValidationException, SerializeException {
093      return getPartSession().write(partType, schema, value);
094   }
095}