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.rest.converters; 014 015import org.apache.juneau.rest.*; 016import org.apache.juneau.utils.*; 017 018/** 019 * Converter for enabling of {@link PojoQuery} support on response objects returned by a <c>@RestMethod</c> method. 020 * 021 * <p> 022 * When enabled, objects in a POJO tree can be filtered using the functionality described in the {@link PojoQuery} 023 * class. 024 * 025 * <p> 026 * The following HTTP request parameters are available for tabular data (e.g. {@code Collections} of {@code Maps}, 027 * arrays of beans, etc...): 028 * <ul class='spaced-list'> 029 * <li> 030 * <c>&s=</c> Search arguments. 031 * <br>Comma-delimited list of key/value pairs representing column names and search tokens. 032 * <br>Example: 033 * <p class='bcode w800'> 034 * &s=name=Bill*,birthDate>2000 035 * </p> 036 * <li> 037 * <c>&v=</c> Visible columns. 038 * <br>Comma-delimited list of column names to display. 039 * <br>Example: 040 * <p class='bcode w800'> 041 * &v=name,birthDate 042 * </p> 043 * <li> 044 * <c>&o=</c> Sort commands. 045 * <br>Comma-delimited list of columns to sort by. 046 * <br>Column names can be suffixed with <js>'+'</js> or <js>'-'</js> to indicate ascending or descending order. 047 * <br>The default is ascending order. 048 * <br>Example: 049 * <p class='bcode w800'> 050 * &o=name,birthDate- 051 * </p> 052 * <li> 053 * <c>&i=</c> Case-insensitive parameter. 054 * <br>Boolean flag for case-insensitive matching on the search parameters. 055 * <li> 056 * <c>&p=</c> - Position parameter. 057 * <br>Only return rows starting at the specified index position (zero-indexed). 058 * <br>Default is {@code 0}. 059 * <li> 060 * <c>&l=</c> Limit parameter. 061 * <br>Only return the specified number of rows. 062 * <br>Default is {@code 0} (meaning return all rows). 063 * </ul> 064 * 065 * <ul class='seealso'> 066 * <li class='jc'>{@link PojoQuery} - Additional information on filtering POJO models. 067 * <li class='jf'>{@link RestContext#REST_converters} - Registering converters with REST resources. 068 * <li class='link'>{@doc juneau-rest-server.Converters} 069 * </ul> 070 */ 071public final class Queryable implements RestConverter { 072 073 /** 074 * Swagger parameters for this converter. 075 */ 076 public static final String SWAGGER_PARAMS="" 077 + "{" 078 + "in:'query'," 079 + "name:'s'," 080 + "description:'" 081 + "Search.\n" 082 + "Key/value pairs representing column names and search tokens.\n" 083 + "\\'*\\' and \\'?\\' can be used as meta-characters in string fields.\n" 084 + "\\'>\\', \\'>=\\', \\'<\\', and \\'<=\\' can be used as limits on numeric and date fields.\n" 085 + "Date fields can be matched with partial dates (e.g. \\'2018\\' to match any date in the year 2018)." 086 + "'," 087 + "type:'array'," 088 + "collectionFormat:'csv'," 089 + "x-examples:{example:'?s=Bill*,birthDate>2000'}" 090 + "}," 091 + "{" 092 + "in:'query'," 093 + "name:'v'," 094 + "description:'" 095 + "View.\n" 096 + "Column names to display." 097 + "'," 098 + "type:'array'," 099 + "collectionFormat:'csv'," 100 + "x-examples:{example:'?v=name,birthDate'}" 101 + "}," 102 + "{" 103 + "in:'query'," 104 + "name:'o'," 105 + "description:'" 106 + "Order by.\n" 107 + "Columns to sort by.\n" 108 + "Column names can be suffixed with \\'+\\' or \\'-\\' to indicate ascending or descending order.\n" 109 + "The default is ascending order." 110 + "'," 111 + "type:'array'," 112 + "collectionFormat:'csv'," 113 + "x-examples:{example:'?o=name,birthDate-'}" 114 + "}," 115 + "{" 116 + "in:'query'," 117 + "name:'i'," 118 + "description:'" 119 + "Case-insensitive.\n" 120 + "Flag for case-insensitive matching on the search parameters." 121 + "'," 122 + "type:'boolean'," 123 + "x-examples:{example:'?i=true'}" 124 + "}," 125 + "{" 126 + "in:'query'," 127 + "name:'p'," 128 + "description:'" 129 + "Position.\n" 130 + "Only return rows starting at the specified index position (zero-indexed).\n" 131 + "Default is 0" 132 + "'," 133 + "type:'integer'," 134 + "x-examples:{example:'?p=100'}" 135 + "}," 136 + "{" 137 + "in:'query'," 138 + "name:'l'," 139 + "description:'" 140 + "Limit.\n" 141 + "Only return the specified number of rows.\n" 142 + "Default is 0 (meaning return all rows)." 143 + "'," 144 + "type:'integer'," 145 + "x-examples:{example:'?l=100'}" 146 + "}" 147 ; 148 149 @Override /* RestConverter */ 150 public Object convert(RestRequest req, Object o) { 151 if (o == null) 152 return null; 153 SearchArgs searchArgs = req.getQuery().getSearchArgs(); 154 if (searchArgs == null) 155 return o; 156 return new PojoQuery(o, req.getBeanSession()).filter(searchArgs); 157 } 158}