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.rest.server.config;
018
019import org.apache.juneau.commons.bean.*;
020import org.apache.juneau.marshall.*;
021import org.apache.juneau.marshall.bson.*;
022import org.apache.juneau.marshall.cbor.*;
023import org.apache.juneau.marshall.csv.*;
024import org.apache.juneau.marshall.hjson.*;
025import org.apache.juneau.marshall.hocon.*;
026import org.apache.juneau.marshall.html.*;
027import org.apache.juneau.marshall.ini.*;
028import org.apache.juneau.marshall.jcs.*;
029import org.apache.juneau.marshall.json.*;
030import org.apache.juneau.marshall.json5.*;
031import org.apache.juneau.marshall.json5l.*;
032import org.apache.juneau.marshall.jsonl.*;
033import org.apache.juneau.marshall.markdown.*;
034import org.apache.juneau.marshall.msgpack.*;
035import org.apache.juneau.marshall.oapi.*;
036import org.apache.juneau.marshall.parquet.*;
037import org.apache.juneau.marshall.plaintext.*;
038import org.apache.juneau.marshall.prototext.*;
039import org.apache.juneau.marshall.serializer.*;
040import org.apache.juneau.marshall.soap.*;
041import org.apache.juneau.marshall.toml.*;
042import org.apache.juneau.marshall.uon.*;
043import org.apache.juneau.marshall.urlencoding.*;
044import org.apache.juneau.marshall.xml.*;
045import org.apache.juneau.marshall.yaml.*;
046import org.apache.juneau.rest.server.*;
047import org.apache.juneau.rest.server.servlet.*;
048
049/**
050 * Predefined configuration for a REST resource that supports all languages
051 * and provides common default configuration values.
052 *
053 * <p>
054 *    Default settings defined:
055 * </p>
056 * <ul class='spaced-list'>
057 *    <li class='ja'>{@link Rest}:
058 *       <ul>
059 *          <li class='jma'>{@link Rest#serializers() serializers}:
060 *             <ul class='javatree'>
061 *                <li class='jc'>{@link HtmlDocSerializer}
062 *                <li class='jc'>{@link HtmlStrippedDocSerializer}
063 *                <li class='jc'>{@link HtmlSchemaDocSerializer}
064 *                <li class='jc'>{@link JsonSerializer}
065 *                <li class='jc'>{@link Json5Serializer}
066 *                <li class='jc'>{@link Json5lSerializer}
067 *                <li class='jc'>{@link JsonSchemaSerializer}
068 *                <li class='jc'>{@link XmlDocSerializer}
069 *                <li class='jc'>{@link UonSerializer}
070 *                <li class='jc'>{@link UrlEncodingSerializer}
071 *                <li class='jc'>{@link OpenApiSerializer}
072 *                <li class='jc'>{@link MsgPackSerializer}
073 *                <li class='jc'>{@link SoapXmlSerializer}
074 *                <li class='jc'>{@link PlainTextSerializer}
075 *             </ul>
076 *          </li>
077 *          <li class='jma'>{@link Rest#parsers() parsers}:
078 *             <ul class='javatree'>
079 *                <li class='jc'>{@link JsonParser}
080 *                <li class='jc'>{@link Json5Parser}
081 *                <li class='jc'>{@link Json5lParser}
082 *                <li class='jc'>{@link XmlParser}
083 *                <li class='jc'>{@link HtmlParser}
084 *                <li class='jc'>{@link UonParser}
085 *                <li class='jc'>{@link UrlEncodingParser}
086 *                <li class='jc'>{@link OpenApiParser}
087 *                <li class='jc'>{@link MsgPackParser}
088 *                <li class='jc'>{@link PlainTextParser}
089 *             </ul>
090 *          </li>
091 *          <li class='jma'>{@link Rest#config() config}:  <js>"${S:juneau.configFile:SYSTEM_DEFAULT}"</js>
092 *    </ul>
093 * </li>
094 *    <li class='ja'>{@link MarshalledConfig}:
095 *       <ul>
096 *          <li class='jma'>{@link BeanConfig#ignoreUnknownBeanProperties() ignoreUnknownBeanProperties}:  <js>"true"</js>
097 *       </ul>
098 *    </li>
099 *    <li class='ja'>{@link SerializerConfig}:
100 *       <ul>
101 *          <li class='jma'>{@link SerializerConfig#uriResolution() uriResolution}:  <js>"ROOT_RELATIVE"</js>
102 *       </ul>
103 *    </li>
104 *    <li class='ja'>{@link HtmlDocConfig}:
105 *       <ul>
106 *          <li class='jma'>{@link HtmlDocConfig#header() header}:  <js>"&lt;h1&gt;${RS:title}&lt;/h1&gt;&lt;h2&gt;${RS:operationSummary:description}&lt;/h2&gt;${C:REST/header}"</js>
107 *          <li class='jma'>{@link HtmlDocConfig#navlinks() navlinks}:  <js>"up: request:/.."</js>
108 *          <li class='jma'>{@link HtmlDocConfig#stylesheet() stylesheet}:  <js>"${C:REST/theme:servlet:/htdocs/themes/devops.css}"</js>
109 *          <li class='jma'>{@link HtmlDocConfig#head() head}:  <js>"${C:REST/head}"</js>
110 *          <li class='jma'>{@link HtmlDocConfig#footer() footer}:  <js>"${C:REST/footer}"</js>
111 *          <li class='jma'>{@link HtmlDocConfig#nowrap() nowrap}:  <js>"true"</js>
112 *       </ul>
113 *    </li>
114 * </ul>
115 *
116 * <p>
117 *    This annotation can be applied to REST resource classes to define common default configurations:
118 * </p>
119 * <p class='bjava'>
120 *    <jc>// Used on a top-level resource.</jc>
121 *    <ja>@Rest</ja>
122 *    <jk>public class</jk> MyResource <jk>extends</jk> RestServlet <jk>implements</jk> BasicUniversalConfig { ... }
123 * </p>
124 * <p class='bjava'>
125 *    <jc>// Used on a child resource.</jc>
126 *    <ja>@Rest</ja>
127 *    <jk>public class</jk> MyResource <jk>extends</jk> RestResource <jk>implements</jk> BasicUniversalConfig { ... }
128 * </p>
129 *
130 * <p>
131 *    Note that the framework will aggregate annotations defined on all classes in the class hierarchy with
132 *    values defined on child classes overriding values defined on parent classes.  That allows any values defined
133 *    on this interface to be overridden by annotations defined on the implemented class.
134 * </p>
135 *
136 * <h2 class='section'>See Also:</h2><ul>
137 *    <li>Related base classes:
138 *    <ul class='javatreec'>
139 *       <li class='jc'>{@link BasicRestServlet}
140 *       <li class='jc'>{@link BasicRestServletGroup}
141 *       <li class='jc'>{@link BasicRestResource}
142 *       <li class='jc'>{@link BasicRestResourceGroup}
143 *    </ul>
144 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestAnnotatedClasses">@Rest-Annotated Class</a>
145 * </ul>
146 */
147// @formatter:off
148@Rest(
149
150   // Default serializers for all Java methods in the class.
151   serializers={
152      HtmlDocSerializer.class, // HTML must be listed first because Internet Explore does not include text/html in their Accept header.
153      HtmlStrippedDocSerializer.class,
154      HtmlSchemaDocSerializer.class,
155      HjsonSerializer.class,
156      HoconSerializer.class,
157      JsonSerializer.class,
158      JcsSerializer.class,
159      Json5Serializer.class,
160      Json5lSerializer.class,
161      JsonlSerializer.class,
162      JsonSchemaSerializer.class,
163      XmlDocSerializer.class,
164      UonSerializer.class,
165      UrlEncodingSerializer.class,
166      OpenApiSerializer.class,
167      BsonSerializer.class,
168      CborSerializer.class,
169      MsgPackSerializer.class,
170      SoapXmlSerializer.class,
171      PlainTextSerializer.class,
172      CsvSerializer.class,
173      YamlSerializer.class,
174      TomlSerializer.class,
175      IniSerializer.class,
176      ParquetSerializer.class,
177      PrototextSerializer.class,
178      MarkdownSerializer.class
179   },
180
181   // Default parsers for all Java methods in the class.
182   parsers={
183      JsonParser.class,
184      Json5Parser.class,
185      Json5lParser.class,
186      JsonlParser.class,
187      XmlParser.class,
188      HtmlParser.class,
189      HjsonParser.class,
190      HoconParser.class,
191      UonParser.class,
192      UrlEncodingParser.class,
193      OpenApiParser.class,
194      BsonParser.class,
195      CborParser.class,
196      MsgPackParser.class,
197      PlainTextParser.class,
198      CsvParser.class,
199      YamlParser.class,
200      TomlParser.class,
201      IniParser.class,
202      ParquetParser.class,
203      PrototextParser.class,
204      MarkdownParser.class
205   },
206
207   // Serializer session properties that clients are allowed to override via HTTP headers/query parameters.
208   allowedSerializerOptions={
209      "useWhitespace",          // WriterSerializer - enable/disable whitespace
210      "maxIndent",              // WriterSerializer - max indentation level
211      "quoteChar",              // WriterSerializer - quote character
212      "keepNullProperties",     // SerializerSession - include null properties
213      "trimStrings",            // SerializerSession - trim string values
214      "addBeanTypes",           // SerializerSession - add bean type annotations
215      "addRootType",            // SerializerSession - add root type annotation
216      "sortCollections",        // SerializerSession - sort collections
217      "sortMaps",               // SerializerSession - sort maps
218      "trimEmptyCollections",   // SerializerSession - trim empty collections
219      "trimEmptyMaps",          // SerializerSession - trim empty maps
220      "binaryFormat",           // OutputStreamSerializer - binary encoding format
221      "escapeSolidus",          // JsonSerializerSession - escape forward slashes
222      "encoding",               // UonSerializerSession - URL-encode characters
223      "paramFormat",            // UonSerializerSession - parameter format style
224      "addNamespaceUrisToRoot", // XmlSerializerSession - add namespace URIs to root
225      "autoDetectNamespaces",   // XmlSerializerSession - auto-detect namespaces
226      "enableNamespaces",       // XmlSerializerSession - enable namespace support
227      "textNodeDelimiter",      // XmlSerializerSession - text node delimiter
228      "addKeyValueTableHeaders",// HtmlSerializerSession - add key/value table headers
229      "detectLabelParameters",  // HtmlSerializerSession - detect label parameters
230      "detectLinksInStrings",   // HtmlSerializerSession - detect links in strings
231      "labelParameter",         // HtmlSerializerSession - label parameter name
232      "uriAnchorText",          // HtmlSerializerSession - URI anchor text strategy
233      "byteArrayFormat",        // CsvSerializerSession - byte array encoding format
234      "allowNestedStructures"   // CsvSerializerSession - allow nested structures
235   },
236
237   // Parser session properties that clients are allowed to override via HTTP headers/query parameters.
238   allowedParserOptions={
239      "trimStrings",            // ParserSession - trim string values
240      "binaryFormat",           // InputStreamParser - binary decoding format
241      "validateEnd",            // JsonParserSession/UonParserSession - validate end of input
242      "decoding",               // UonParserSession - URL-decode characters
243      "expandedParams",         // UrlEncodingParserSession - expanded parameters
244      "preserveRootElement",    // XmlParserSession - preserve root element
245      "validating"              // XmlParserSession - validate XML
246   }
247)
248public interface BasicUniversalConfig extends DefaultConfig, DefaultHtmlConfig {}