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 <code>@RestMethod</code> 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 * <code>&s=</code> 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 * <code>&v=</code> 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 * <code>&o=</code> 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 * <code>&i=</code> Case-insensitive parameter. 054 * <br>Boolean flag for case-insensitive matching on the search parameters. 055 * <li> 056 * <code>&p=</code> - Position parameter. 057 * <br>Only return rows starting at the specified index position (zero-indexed). 058 * <br>Default is {@code 0}. 059 * <li> 060 * <code>&l=</code> 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 * <h5 class='section'>See Also:</h5> 066 * <ul> 067 * <li class='jc'>{@link PojoQuery} - Additional information on filtering POJO models. 068 * <li class='jf'>{@link RestContext#REST_converters} - Registering converters with REST resources. 069 * <li class='link'>{@doc juneau-rest-server.Converters} 070 * </ul> 071 */ 072public final class Queryable implements RestConverter { 073 074 /** 075 * Swagger parameters for this converter. 076 */ 077 public static final String SWAGGER_PARAMS="" 078 + "{" 079 + "in:'query'," 080 + "name:'s'," 081 + "description:'" 082 + "Search.\n" 083 + "Key/value pairs representing column names and search tokens.\n" 084 + "\\'*\\' and \\'?\\' can be used as meta-characters in string fields.\n" 085 + "\\'>\\', \\'>=\\', \\'<\\', and \\'<=\\' can be used as limits on numeric and date fields.\n" 086 + "Date fields can be matched with partial dates (e.g. \\'2018\\' to match any date in the year 2018)." 087 + "'," 088 + "type:'array'," 089 + "collectionFormat:'csv'," 090 + "x-examples:{example:'?s=Bill*,birthDate>2000'}" 091 + "}," 092 + "{" 093 + "in:'query'," 094 + "name:'v'," 095 + "description:'" 096 + "View.\n" 097 + "Column names to display." 098 + "'," 099 + "type:'array'," 100 + "collectionFormat:'csv'," 101 + "x-examples:{example:'?v=name,birthDate'}" 102 + "}," 103 + "{" 104 + "in:'query'," 105 + "name:'o'," 106 + "description:'" 107 + "Order by.\n" 108 + "Columns to sort by.\n" 109 + "Column names can be suffixed with \\'+\\' or \\'-\\' to indicate ascending or descending order.\n" 110 + "The default is ascending order." 111 + "'," 112 + "type:'array'," 113 + "collectionFormat:'csv'," 114 + "x-examples:{example:'?o=name,birthDate-'}" 115 + "}," 116 + "{" 117 + "in:'query'," 118 + "name:'i'," 119 + "description:'" 120 + "Case-insensitive.\n" 121 + "Flag for case-insensitive matching on the search parameters." 122 + "'," 123 + "type:'boolean'," 124 + "x-examples:{example:'?i=true'}" 125 + "}," 126 + "{" 127 + "in:'query'," 128 + "name:'p'," 129 + "description:'" 130 + "Position.\n" 131 + "Only return rows starting at the specified index position (zero-indexed).\n" 132 + "Default is 0" 133 + "'," 134 + "type:'integer'," 135 + "x-examples:{example:'?p=100'}" 136 + "}," 137 + "{" 138 + "in:'query'," 139 + "name:'l'," 140 + "description:'" 141 + "Limit.\n" 142 + "Only return the specified number of rows.\n" 143 + "Default is 0 (meaning return all rows)." 144 + "'," 145 + "type:'integer'," 146 + "x-examples:{example:'?l=100'}" 147 + "}" 148 ; 149 150 @Override /* RestConverter */ 151 public Object convert(RestRequest req, Object o) { 152 if (o == null) 153 return null; 154 SearchArgs searchArgs = req.getQuery().getSearchArgs(); 155 if (searchArgs == null) 156 return o; 157 return new PojoQuery(o, req.getBeanSession()).filter(searchArgs); 158 } 159}