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 * 018 * <h5 class='section'>See Also:</h5><ul> 019 * <li class='link'><a class="doclink" href="../../../../../index.html#jm.XmlDetails">XML Details</a> 020 021 * </ul> 022 */ 023public enum XmlFormat { 024 025 /** 026 * Normal formatting (default). 027 * 028 * <p> 029 * On a bean class, implies {@link #ELEMENTS} meaning bean properties will be serialized as child elements by default. 030 * 031 * <p> 032 * On a bean property, implies {@link #ELEMENT} meaning the bean property will be serialized as a child element. 033 */ 034 DEFAULT, 035 036 /** 037 * Render a bean property as an attribute instead of an element. 038 * 039 * <p> 040 * Only applicable for bean properties, not bean classes. 041 * 042 * <p> 043 * Can only be applied to properties (methods/fields) of class types that can be convertible to <c>Strings</c>. 044 */ 045 ATTR, 046 047 /** 048 * Render property as attributes instead of an element. 049 * 050 * <p> 051 * On a bean class, implies bean properties will be serialized as attributes instead of child elements by default. 052 * 053 * <p> 054 * On bean properties, implies that the bean property value itself should be serialized as attributes on the bean 055 * element. 056 * The bean property data type must be of class type <c>Map<Object,Object></c> where both 057 * objects are convertible to <c>Strings</c>. 058 */ 059 ATTRS, 060 061 /** 062 * Render property as an element instead of an attribute. 063 * 064 * <p> 065 * Only applicable for bean properties, not bean classes. 066 * 067 * <p> 068 * Used to override the behavior of the {@link #ATTRS} format applied to the bean class. 069 */ 070 ELEMENT, 071 072 /** 073 * Render property value directly as the contents of the element. 074 * 075 * <p> 076 * On a bean class, implies that bean properties will be serialized as child elements. 077 * Note that this is equivalent to {@link #DEFAULT}. 078 * 079 * <p> 080 * Only applicable for objects of type array/Collection. 081 * 082 * <p> 083 * On a bean property, implies that the bean property value itself should be serialized as child elements of the 084 * bean element. 085 */ 086 ELEMENTS, 087 088 /** 089 * Same as {@link #ELEMENTS} except primitive types (string/boolean/number/null for example) are not wrapped in elements. 090 * 091 * <p> 092 * Only applicable for bean properties, not bean classes. 093 * 094 * <p> 095 * Only applicable for objects of type array/Collection. 096 * 097 * <p> 098 * Use of this format may cause data type loss during parsing if the types cannot be inferred through reflection. 099 */ 100 MIXED, 101 102 /** 103 * Same as {@link XmlFormat#MIXED}, but whitespace in text nodes are not trimmed during parsing. 104 * 105 * <p> 106 * An example use is HTML5 <xt><pre></xt> where whitespace should not be discarded. 107 */ 108 MIXED_PWS, 109 110 /** 111 * Render property value as the text content of the element. 112 * 113 * <p> 114 * Similar to {@link #MIXED} but value must be a single value, not a collection. 115 * 116 * <p> 117 * Only applicable for bean properties, not bean classes. 118 * 119 * <p> 120 * Use of this format may cause data type loss during parsing if the type cannot be inferred through reflection. 121 */ 122 TEXT, 123 124 /** 125 * Same as {@link XmlFormat#TEXT}, but whitespace in text node is not trimmed during parsing. 126 */ 127 TEXT_PWS, 128 129 /** 130 * Same as {@link #TEXT} except the content is expected to be fully-formed XML that will get serialized as-is. 131 * 132 * <p> 133 * During parsing, this XML text will be re-serialized and set on the property. 134 * 135 * <p> 136 * Only applicable for bean properties, not bean classes. 137 * 138 * <p> 139 * Use of this format may cause data type loss during parsing if the type cannot be inferred through reflection. 140 */ 141 XMLTEXT, 142 143 /** 144 * Prevents collections and arrays from being enclosed in <xt><array></xt> elements. 145 * 146 * <p> 147 * Can only be applied to properties (methods/fields) of type collection or array, or collection classes. 148 */ 149 COLLAPSED, 150 151 /** 152 * Identifies a void element. 153 * 154 * <p> 155 * Only applicable for bean classes. 156 * 157 * <p> 158 * Identifies an element that never contains content. 159 * 160 * <p> 161 * The main difference in behavior is how non-void empty elements are handled in the HTML serializer. 162 * Void elements are serialized as collapsed nodes (e.g. <js>"<br/>"</js>) whereas non-void empty elements are 163 * serialized with an end tag (e.g. "<p></p>"). 164 */ 165 VOID; 166 167 /** 168 * Returns <jk>true</jk> if this format is one of those specified. 169 * 170 * @param formats The formats to match against. 171 * @return <jk>true</jk> if this format is one of those specified. 172 */ 173 public boolean isOneOf(XmlFormat...formats) { 174 for (XmlFormat format : formats) 175 if (format == this) 176 return true; 177 return false; 178 } 179}