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;
018
019import static org.apache.juneau.common.utils.Utils.*;
020import static org.apache.juneau.internal.ClassUtils.*;
021
022import java.util.*;
023
024import org.apache.juneau.annotation.*;
025
026/**
027 * Parent class for all non-bean filters.
028 *
029 * <p>
030 * Marshalled filters are used to control aspects of how POJOs are handled during serialization and parsing.
031 *
032 * <p>
033 * Marshalled filters are created by {@link Builder} which is the programmatic equivalent to the {@link Marshalled @Marshalled}
034 * annotation.
035 *
036 * <h5 class='section'>See Also:</h5><ul>
037
038 * </ul>
039 */
040public class MarshalledFilter {
041
042   //-----------------------------------------------------------------------------------------------------------------
043   // Static
044   //-----------------------------------------------------------------------------------------------------------------
045
046   /**
047    * Create a new instance of this POJO filter.
048    *
049    * @param <T> The POJO class being filtered.
050    * @param marshalledClass The POJO class being filtered.
051    * @return A new {@link Builder} object.
052    */
053   public static <T> Builder create(Class<T> marshalledClass) {
054      return new Builder(marshalledClass);
055   }
056
057   //-----------------------------------------------------------------------------------------------------------------
058   // Builder
059   //-----------------------------------------------------------------------------------------------------------------
060
061   /**
062    * Builder class.
063    */
064   public static class Builder {
065
066      Class<?> marshalledClass;
067
068      Class<?> implClass;
069      String example;
070
071      /**
072       * Constructor.
073       *
074       * @param marshalledClass The class that this filter applies to.
075       */
076      protected Builder(Class<?> marshalledClass) {
077         this.marshalledClass = marshalledClass;
078      }
079
080      /**
081       * Applies the information in the specified list of {@link Marshalled @Marshalled} annotations to this filter.
082       *
083       * @param annotations The annotations to apply.
084       * @return This object.
085       */
086      public Builder applyAnnotations(List<Marshalled> annotations) {
087
088         annotations.forEach(x -> {
089            if (isNotVoid(x.implClass()))
090               implClass(x.implClass());
091            if (isNotEmpty(x.example()))
092               example(x.example());
093         });
094         return this;
095      }
096
097      /**
098       * Implementation class.
099       *
100       * @param value The new value for this setting.
101       * @return This object.
102       */
103      public Builder implClass(Class<?> value) {
104         this.implClass = value;
105         return this;
106      }
107
108      /**
109       * POJO example in Simplified JSON format.
110       *
111       * @param value The new value for this annotation.
112       * @return This object.
113       */
114      public Builder example(String value) {
115         this.example = value;
116         return this;
117      }
118
119      /**
120       * Creates a {@link MarshalledFilter} with settings in this builder class.
121       *
122       * @return A new {@link MarshalledFilter} instance.
123       */
124      public MarshalledFilter build() {
125         return new MarshalledFilter(this);
126      }
127   }
128
129   //-----------------------------------------------------------------------------------------------------------------
130   // Instance
131   //-----------------------------------------------------------------------------------------------------------------
132
133   private final Class<?> marshalledClass;
134   private final Class<?> implClass;
135   private final String example;
136
137   /**
138    * Constructor.
139    *
140    * @param builder The builder for this object.
141    */
142   protected MarshalledFilter(Builder builder) {
143      this.marshalledClass = builder.marshalledClass;
144      this.implClass = builder.implClass;
145      this.example = builder.example;
146   }
147
148   /**
149    * Returns the class that this filter applies to.
150    *
151    * @return The class that this filter applies to.
152    */
153   public Class<?> getMarshalledClass() {
154      return marshalledClass;
155   }
156
157   /**
158    * Returns the implementation class associated with this class.
159    *
160    * @return The implementation class associated with this class, or <jk>null</jk> if no implementation class is associated.
161    */
162   public Class<?> getImplClass() {
163      return implClass;
164   }
165
166   /**
167    * Returns the example string with this class.
168    *
169    * @return The example string associated with this class, or <jk>null</jk> if no example string is associated.
170    */
171   public String getExample() {
172      return example;
173   }
174}