001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.xml.annotation;
014
015/**
016 * XML format to use when serializing a POJO.
017 */
018public enum XmlFormat {
019
020   /**
021    * Normal formatting (default).
022    * 
023    * <p>
024    * On a bean class, implies {@link #ELEMENTS} meaning bean properties will be serialized as child elements by default.
025    * 
026    * <p>
027    * On a bean property, implies {@link #ELEMENT} meaning the bean property will be serialized as a child element.
028    */
029   DEFAULT,
030
031   /**
032    * Render a bean property as an attribute instead of an element.
033    * 
034    * <p>
035    * Only applicable for bean properties, not bean classes.
036    * 
037    * <p>
038    * Can only be applied to properties (methods/fields) of class types that can be convertible to <code>Strings</code>.
039    */
040   ATTR,
041
042   /**
043    * Render property as attributes instead of an element.
044    * 
045    * <p>
046    * On a bean class, implies bean properties will be serialized as attributes instead of child elements by default.
047    * 
048    * <p>
049    * On bean properties, implies that the bean property value itself should be serialized as attributes on the bean
050    * element.
051    * The bean property data type must be of class type <code>Map&lt;Object,Object&gt;</code> where both
052    * objects are convertible to <code>Strings</code>.
053    */
054   ATTRS,
055
056   /**
057    * Render property as an element instead of an attribute.
058    * 
059    * <p>
060    * Only applicable for bean properties, not bean classes.
061    * 
062    * <p>
063    * Used to override the behavior of the {@link #ATTRS} format applied to the bean class.
064    */
065   ELEMENT,
066
067   /**
068    * Render property value directly as the contents of the element.
069    * 
070    * <p>
071    * On a bean class, implies that bean properties will be serialized as child elements.
072    * Note that this is equivalent to {@link #DEFAULT}.
073    * 
074    * <p>
075    * Only applicable for objects of type array/Collection.
076    * 
077    * <p>
078    * On a bean property, implies that the bean property value itself should be serialized as child elements of the
079    * bean element.
080    */
081   ELEMENTS,
082
083   /**
084    * Same as {@link #ELEMENTS} except primitive types (e.g. string/boolean/number/null) are not wrapped in elements.
085    * 
086    * <p>
087    * Only applicable for bean properties, not bean classes.
088    * 
089    * <p>
090    * Only applicable for objects of type array/Collection.
091    * 
092    * <p>
093    * Use of this format may cause data type loss during parsing if the types cannot be inferred through reflection.
094    */
095   MIXED,
096
097   /**
098    * Same as {@link XmlFormat#MIXED}, but whitespace in text nodes are not trimmed during parsing.
099    * 
100    * <p>
101    * An example use is HTML5 <xt>&lt;pre&gt;</xt> where whitespace should not be discarded.
102    */
103   MIXED_PWS,
104
105   /**
106    * Render property value as the text content of the element.
107    * 
108    * <p>
109    * Similar to {@link #MIXED} but value must be a single value, not a collection.
110    * 
111    * <p>
112    * Only applicable for bean properties, not bean classes.
113    * 
114    * <p>
115    * Use of this format may cause data type loss during parsing if the type cannot be inferred through reflection.
116    */
117   TEXT,
118
119   /**
120    * Same as {@link XmlFormat#TEXT}, but whitespace in text node is not trimmed during parsing.
121    */
122   TEXT_PWS,
123
124   /**
125    * Same as {@link #TEXT} except the content is expected to be fully-formed XML that will get serialized as-is.
126    * 
127    * <p>
128    * During parsing, this XML text will be re-serialized and set on the property.
129    * 
130    * <p>
131    * Only applicable for bean properties, not bean classes.
132    * 
133    * <p>
134    * Use of this format may cause data type loss during parsing if the type cannot be inferred through reflection.
135    */
136   XMLTEXT,
137
138   /**
139    * Prevents collections and arrays from being enclosed in <xt>&lt;array&gt;</xt> elements.
140    * 
141    * <p>
142    * Can only be applied to properties (methods/fields) of type collection or array, or collection classes.
143    */
144   COLLAPSED,
145
146   /**
147    * Identifies a void element.
148    * 
149    * <p>
150    * Only applicable for bean classes.
151    * 
152    * <p>
153    * Identifies an element that never contains content.
154    * 
155    * <p>
156    * The main difference in behavior is how non-void empty elements are handled in the HTML serializer.
157    * Void elements are serialized as collapsed nodes (e.g. <js>"&lt;br/&gt;"</js>) whereas non-void empty elements are
158    * serialized with an end tag (e.g. "&lt;p&gt;&lt;/p&gt;").
159    */
160   VOID;
161
162   /**
163    * Returns <jk>true</jk> if this format is one of those specified.
164    * 
165    * @param formats The formats to match against.
166    * @return <jk>true</jk> if this format is one of those specified.
167    */
168   public boolean isOneOf(XmlFormat...formats) {
169      for (XmlFormat format : formats)
170         if (format == this)
171            return true;
172      return false;
173   }
174}