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.oapi; 014 015/** 016 * Configurable properties common to both the {@link OpenApiSerializer} and {@link OpenApiParser} classes. 017 */ 018public interface OpenApiCommon { 019 020 /** 021 * Property prefix. 022 */ 023 static final String PREFIX = "OpenApi"; 024 025 /** 026 * Configuration property: Default format for HTTP parts. 027 * 028 * <h5 class='section'>Property:</h5> 029 * <ul class='spaced-list'> 030 * <li><b>ID:</b> {@link org.apache.juneau.oapi.OpenApiCommon#OAPI_format OAPI_format} 031 * <li><b>Name:</b> <js>"OpenApi.format.s"</js> 032 * <li><b>Data type:</b> {@link org.apache.juneau.httppart.HttpPartFormat} 033 * <li><b>System property:</b> <c>OpenApi.format</c> 034 * <li><b>Environment variable:</b> <c>OPENAPI_FORMAT</c> 035 * <li><b>Default:</b> <js>"NO_FORMAT"</js> 036 * <li><b>Session property:</b> <jk>false</jk> 037 * <li><b>Annotations:</b> 038 * <ul> 039 * <li class='ja'>{@link org.apache.juneau.oapi.annotation.OpenApiConfig#format()} 040 * </ul> 041 * <li><b>Methods:</b> 042 * <ul> 043 * <li class='jm'>{@link org.apache.juneau.oapi.OpenApiSerializerBuilder#format(org.apache.juneau.httppart.HttpPartFormat)} 044 * <li class='jm'>{@link org.apache.juneau.oapi.OpenApiParserBuilder#format(org.apache.juneau.httppart.HttpPartFormat)} 045 * </ul> 046 * </ul> 047 * 048 * <h5 class='section'>Description:</h5> 049 * 050 * <p> 051 * Specifies the format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#format()}. 052 * 053 * <p> 054 * Possible values: 055 * <ul class='javatree'> 056 * <li class='jc'>{@link org.apache.juneau.httppart.HttpPartFormat} 057 * <ul> 058 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#UON UON} - UON notation (e.g. <js>"'foo bar'"</js>). 059 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#INT32 INT32} - Signed 32 bits. 060 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#INT64 INT64} - Signed 64 bits. 061 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#FLOAT FLOAT} - 32-bit floating point number. 062 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#DOUBLE DOUBLE} - 64-bit floating point number. 063 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#BYTE BYTE} - BASE-64 encoded characters. 064 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#BINARY BINARY} - Hexadecimal encoded octets (e.g. <js>"00FF"</js>). 065 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#BINARY_SPACED BINARY_SPACED} - Spaced-separated hexadecimal encoded octets (e.g. <js>"00 FF"</js>). 066 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#DATE DATE} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>. 067 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#DATE_TIME DATE_TIME} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>. 068 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#PASSWORD PASSWORD} - Used to hint UIs the input needs to be obscured. 069 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#NO_FORMAT NO_FORMAT} - (default) Not specified. 070 * </ul> 071 * </ul> 072 * 073 * <h5 class='section'>Example:</h5> 074 * <p class='bcode w800'> 075 * <jc>// Create a plain-text serializer.</jc> 076 * OpenApiSerializer s1 = OpenApiSerializer 077 * .<jsm>create</jsm>() 078 * .build(); 079 * 080 * <jc>// Create a UON serializer.</jc> 081 * OpenApiSerializer s2 = OpenApiSerializer 082 * .<jsm>create</jsm>() 083 * .format(<jsf>UON</jsf>) 084 * .build(); 085 * 086 * String string = <js>"foo bar"</js>; 087 * 088 * <jc>// Produces: "foo bar"</jc> 089 * String v1 = s.serialize(string); 090 * 091 * <jc>// Produces: "'foo bar'"</jc> 092 * String v2 = s2.serialize(string); 093 * </p> 094 */ 095 public static final String OAPI_format = PREFIX + ".format.s"; 096 097 /** 098 * Configuration property: Default collection format for HTTP parts. 099 * 100 * <h5 class='section'>Property:</h5> 101 * <ul class='spaced-list'> 102 * <li><b>ID:</b> {@link org.apache.juneau.oapi.OpenApiCommon#OAPI_collectionFormat OAPI_collectionFormat} 103 * <li><b>Name:</b> <js>"OpenApi.format.s"</js> 104 * <li><b>Data type:</b> {@link org.apache.juneau.httppart.HttpPartCollectionFormat} 105 * <li><b>System property:</b> <c>OpenApi.collectionFormat</c> 106 * <li><b>Environment variable:</b> <c>OPENAPI_COLLECTIONFORMAT</c> 107 * <li><b>Default:</b> <js>"NO_COLLECTION_FORMAT"</js> 108 * <li><b>Session property:</b> <jk>false</jk> 109 * <li><b>Annotations:</b> 110 * <ul> 111 * <li class='ja'>{@link org.apache.juneau.oapi.annotation.OpenApiConfig#collectionFormat()} 112 * </ul> 113 * <li><b>Methods:</b> 114 * <ul> 115 * <li class='jm'>{@link org.apache.juneau.oapi.OpenApiSerializerBuilder#collectionFormat(org.apache.juneau.httppart.HttpPartCollectionFormat)} 116 * <li class='jm'>{@link org.apache.juneau.oapi.OpenApiParserBuilder#collectionFormat(org.apache.juneau.httppart.HttpPartCollectionFormat)} 117 * </ul> 118 * </ul> 119 * 120 * <h5 class='section'>Description:</h5> 121 * 122 * <p> 123 * Specifies the collection format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#collectionFormat()}. 124 * 125 * <p> 126 * Possible values: 127 * <ul class='javatree'> 128 * <li class='jc'>{@link org.apache.juneau.httppart.HttpPartFormat} 129 * <ul> 130 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#CSV CSV} - (default) Comma-separated values (e.g. <js>"foo,bar"</js>). 131 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#SSV SSV} - Space-separated values (e.g. <js>"foo bar"</js>). 132 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#TSV TSV} - Tab-separated values (e.g. <js>"foo\tbar"</js>). 133 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#PIPES PIPES} - Pipe-separated values (e.g. <js>"foo|bar"</js>). 134 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#MULTI MULTI} - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>). 135 * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#UONC UONC} - UON collection notation (e.g. <js>"@(foo,bar)"</js>). 136 * </ul> 137 * </ul> 138 * 139 * <h5 class='section'>Example:</h5> 140 * <p class='bcode w800'> 141 * <jc>// Create a serializer using CSV for collections.</jc> 142 * OpenApiSerializer s1 = OpenApiSerializer 143 * .<jsm>create</jsm>() 144 * .collectionFormat(<jsf>CSV</jsf>) 145 * .build(); 146 * 147 * <jc>// Create a serializer using UON for collections.</jc> 148 * OpenApiSerializer s2 = OpenApiSerializer 149 * .<jsm>create</jsm>() 150 * .collectionFormat(<jsf>UON</jsf>) 151 * .build(); 152 * 153 * <jc>// An arbitrary data structure.</jc> 154 * OList l = OList.<jsm>of</jsm>( 155 * <js>"foo"</js>, 156 * <js>"bar"</js>, 157 * OMap.<jsm>of</jsm>( 158 * <js>"baz"</js>, OList.<jsm>of</jsm>(<js>"qux"</js>,<js>"true"</js>,<js>"123"</js>) 159 * ) 160 * ); 161 * 162 * <jc>// Produces: "foo=bar,baz=qux\,true\,123"</jc> 163 * String v1 = s1.serialize(l) 164 * 165 * <jc>// Produces: "(foo=bar,baz=@(qux,'true','123'))"</jc> 166 * String v2 = s2.serialize(l) 167 * </p> 168 */ 169 public static final String OAPI_collectionFormat = PREFIX + ".collectionformat.s"; 170}