Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id C19EA200C7E for ; Mon, 8 May 2017 17:32:42 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id C0508160BA5; Mon, 8 May 2017 15:32:42 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 43BD2160BBF for ; Mon, 8 May 2017 17:32:41 +0200 (CEST) Received: (qmail 17309 invoked by uid 500); 8 May 2017 15:32:40 -0000 Mailing-List: contact commits-help@juneau.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@juneau.incubator.apache.org Delivered-To: mailing list commits@juneau.incubator.apache.org Received: (qmail 17296 invoked by uid 99); 8 May 2017 15:32:40 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 08 May 2017 15:32:40 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 06ABD18140E for ; Mon, 8 May 2017 15:32:40 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -3.822 X-Spam-Level: X-Spam-Status: No, score=-3.822 tagged_above=-999 required=6.31 tests=[KAM_LINEPADDING=1.2, RCVD_IN_DNSWL_HI=-5, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-0.001, SPF_PASS=-0.001] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id MOaKDMi3VzyO for ; Mon, 8 May 2017 15:32:34 +0000 (UTC) Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with SMTP id 34F985FE03 for ; Mon, 8 May 2017 15:32:33 +0000 (UTC) Received: (qmail 16996 invoked by uid 99); 8 May 2017 15:32:31 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 08 May 2017 15:32:31 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 66B65DFE61; Mon, 8 May 2017 15:32:31 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: jamesbognar@apache.org To: commits@juneau.incubator.apache.org Date: Mon, 08 May 2017 15:32:38 -0000 Message-Id: In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [08/51] [partial] incubator-juneau-website git commit: Support for passing in more class types to REST methods. archived-at: Mon, 08 May 2017 15:32:42 -0000 http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/f1f17bc3/content/site/apidocs/src-html/org/apache/juneau/rest/RequestQuery.html ---------------------------------------------------------------------- diff --git a/content/site/apidocs/src-html/org/apache/juneau/rest/RequestQuery.html b/content/site/apidocs/src-html/org/apache/juneau/rest/RequestQuery.html new file mode 100644 index 0000000..a2f20bf --- /dev/null +++ b/content/site/apidocs/src-html/org/apache/juneau/rest/RequestQuery.html @@ -0,0 +1,359 @@ + + + +Source code + + + +
+
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;
+014
+015import java.lang.reflect.*;
+016import java.util.*;
+017
+018import javax.servlet.http.*;
+019
+020import org.apache.juneau.*;
+021import org.apache.juneau.internal.*;
+022import org.apache.juneau.parser.*;
+023import org.apache.juneau.urlencoding.*;
+024
+025/**
+026 * Represents the query parameters in an HTTP request.
+027 */
+028@SuppressWarnings("unchecked")
+029public final class RequestQuery extends LinkedHashMap<String,String[]> {
+030   private static final long serialVersionUID = 1L;
+031
+032   private UrlEncodingParser parser;
+033   private BeanSession beanSession;
+034
+035   RequestQuery setParser(UrlEncodingParser parser) {
+036      this.parser = parser;
+037      return this;
+038   }
+039
+040   RequestQuery setBeanSession(BeanSession beanSession) {
+041      this.beanSession = beanSession;
+042      return this;
+043   }
+044
+045   /**
+046    * Sets a request query parameter value.
+047    *
+048    * @param name The parameter name.
+049    * @param value The parameter value.
+050    */
+051   public void put(String name, Object value) {
+052      put(name, new String[]{StringUtils.toString(value)});
+053   }
+054
+055   /**
+056    * Returns a query parameter value.
+057    * <p>
+058    * Same as {@link HttpServletRequest#getParameter(String)} except only looks in the URL string, not parameters from URL-Encoded FORM posts.
+059    * <p>
+060    * This method can be used to retrieve a parameter without triggering the underlying servlet API to load and parse the request body.
+061    *
+062    * @param name The URL parameter name.
+063    * @return The parameter value, or <jk>null</jk> if parameter not specified or has no value (e.g. <js>"&amp;foo"</js>.
+064    */
+065   public String getFirst(String name) {
+066      String[] v = get(name);
+067      if (v == null || v.length == 0)
+068         return null;
+069      if (v.length == 1 && v[0] != null && v[0].isEmpty()) {
+070         // Fix for behavior difference between Tomcat and WAS.
+071         // getParameter("foo") on "&foo" in Tomcat returns "".
+072         // getParameter("foo") on "&foo" in WAS returns null.
+073         if (containsKey(name))
+074            return null;
+075      }
+076      return v[0];
+077   }
+078
+079   /**
+080    * Same as {@link #getFirst(String)} but returns the specified default value if the query parameter was not specified.
+081    *
+082    * @param name The URL parameter name.
+083    * @param def The default value.
+084    * @return The parameter value, or the default value if parameter not specified or has no value (e.g. <js>"&amp;foo"</js>.
+085    */
+086   public String getFirst(String name, String def) {
+087      String s = getFirst(name);
+088      return s == null ? def : s;
+089   }
+090
+091   /**
+092    * Returns the specified query parameter value converted to a POJO.
+093    * <p>
+094    * This method can be used to retrieve a parameter without triggering the underlying servlet API to load and parse the request body.
+095    * <p>
+096    * <h5 class='section'>Examples:</h5>
+097    * <p class='bcode'>
+098    *    <jc>// Parse into an integer.</jc>
+099    *    <jk>int</jk> myparam = req.getQueryParameter(<js>"myparam"</js>, <jk>int</jk>.<jk>class</jk>);
+100    *
+101    *    <jc>// Parse into an int array.</jc>
+102    *    <jk>int</jk>[] myparam = req.getQueryParameter(<js>"myparam"</js>, <jk>int</jk>[].<jk>class</jk>);
+103
+104    *    <jc>// Parse into a bean.</jc>
+105    *    MyBean myparam = req.getQueryParameter(<js>"myparam"</js>, MyBean.<jk>class</jk>);
+106    *
+107    *    <jc>// Parse into a linked-list of objects.</jc>
+108    *    List myparam = req.getQueryParameter(<js>"myparam"</js>, LinkedList.<jk>class</jk>);
+109    *
+110    *    <jc>// Parse into a map of object keys/values.</jc>
+111    *    Map myparam = req.getQueryParameter(<js>"myparam"</js>, TreeMap.<jk>class</jk>);
+112    * </p>
+113    *
+114    * @param name The parameter name.
+115    * @param type The class type to convert the parameter value to.
+116    * @param <T> The class type to convert the parameter value to.
+117    * @return The parameter value converted to the specified class type.
+118    * @throws ParseException
+119    */
+120   public <T> T get(String name, Class<T> type) throws ParseException {
+121      return get(name, beanSession.getClassMeta(type));
+122   }
+123
+124   /**
+125    * Same as {@link #get(String, Class)} except returns a default value if not found.
+126    *
+127    * @param name The parameter name.
+128    * @param def The default value if the parameter was not specified or is <jk>null</jk>.
+129    * @param type The class type to convert the parameter value to.
+130    * @param <T> The class type to convert the parameter value to.
+131    * @return The parameter value converted to the specified class type.
+132    * @throws ParseException
+133    */
+134   public <T> T get(String name, T def, Class<T> type) throws ParseException {
+135      return get(name, def, beanSession.getClassMeta(type));
+136   }
+137
+138   /**
+139    * Returns the specified query parameter value converted to a POJO.
+140    * <p>
+141    * This method can be used to retrieve a parameter without triggering the underlying servlet API to load and parse the request body.
+142    * <p>
+143    * Use this method if you want to parse into a parameterized <code>Map</code>/<code>Collection</code> object.
+144    * <p>
+145    * <h5 class='section'>Examples:</h5>
+146    * <p class='bcode'>
+147    *    <jc>// Parse into a linked-list of strings.</jc>
+148    *    Listt&lt;String&gt; myparam = req.getQueryParameter(<js>"myparam"</js>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
+149    *
+150    *    <jc>// Parse into a linked-list of linked-lists of strings.</jc>
+151    *    Listt&lt;List&lt;String&gt;&gt; myparam = req.getQueryParameter(<js>"myparam"</js>, LinkedList.<jk>class</jk>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
+152    *
+153    *    <jc>// Parse into a map of string keys/values.</jc>
+154    *    Map&lt;String,String&gt; myparam = req.getQueryParameter(<js>"myparam"</js>, TreeMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
+155    *
+156    *    <jc>// Parse into a map containing string keys and values of lists containing beans.</jc>
+157    *    Map&lt;String,List&lt;MyBean&gt;&gt; myparam = req.getQueryParameter(<js>"myparam"</js>, TreeMap.<jk>class</jk>, String.<jk>class</jk>, List.<jk>class</jk>, MyBean.<jk>class</jk>);
+158    * </p>
+159    *
+160    * @param name The parameter name.
+161    * @param type The type of object to create.
+162    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
+163    * @param args The type arguments of the class if it's a collection or map.
+164    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
+165    *    <br>Ignored if the main type is not a map or collection.
+166    * @param <T> The class type to convert the parameter value to.
+167    * @return The parameter value converted to the specified class type.
+168    * @throws ParseException
+169    */
+170   public <T> T get(String name, Type type, Type...args) throws ParseException {
+171      return (T)parse(name, beanSession.getClassMeta(type, args));
+172   }
+173
+174   /**
+175    * Same as {@link #get(String, Class)} except returns a default value if not found.
+176    *
+177    * @param name The parameter name.
+178    * @param type The type of object to create.
+179    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
+180    * @param args The type arguments of the class if it's a collection or map.
+181    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
+182    *    <br>Ignored if the main type is not a map or collection.
+183    * @param def The default value if the parameter was not specified or is <jk>null</jk>.
+184    * @param <T> The class type to convert the parameter value to.
+185    * @return The parameter value converted to the specified class type.
+186    * @throws ParseException
+187    */
+188   public <T> T get(String name, Object def, Type type, Type...args) throws ParseException {
+189      return (T)parse(name, def, beanSession.getClassMeta(type, args));
+190   }
+191
+192   /**
+193    * Same as {@link #get(String, Class)} except for use on multi-part parameters
+194    * (e.g. <js>"&amp;key=1&amp;key=2&amp;key=3"</js> instead of <js>"&amp;key=(1,2,3)"</js>).
+195    * <p>
+196    * This method must only be called when parsing into classes of type Collection or array.
+197    *
+198    * @param name The query parameter name.
+199    * @param c The class type to convert the parameter value to.
+200    * @param <T> The class type to convert the parameter value to.
+201    * @return The query parameter value converted to the specified class type.
+202    * @throws ParseException
+203    */
+204   public <T> T getAll(String name, Class<T> c) throws ParseException {
+205      return getAll(name, beanSession.getClassMeta(c));
+206   }
+207
+208   /**
+209    * Same as {@link #get(String, Type, Type...)} except for use on multi-part parameters
+210    * (e.g. <js>"&amp;key=1&amp;key=2&amp;key=3"</js> instead of <js>"&amp;key=(1,2,3)"</js>).
+211    * <p>
+212    * This method must only be called when parsing into classes of type Collection or array.
+213    *
+214    * @param name The query parameter name.
+215    * @param type The type of object to create.
+216    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
+217    * @param args The type arguments of the class if it's a collection or map.
+218    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
+219    *    <br>Ignored if the main type is not a map or collection.
+220    * @param <T> The class type to convert the parameter value to.
+221    * @return The query parameter value converted to the specified class type.
+222    * @throws ParseException
+223    */
+224   public <T> T getAll(String name, Type type, Type...args) throws ParseException {
+225      return (T)parseAll(name, beanSession.getClassMeta(type, args));
+226   }
+227
+228   /**
+229    * Returns <jk>true</jk> if the request contains any of the specified query parameters.
+230    *
+231    * @param params The list of parameters to check for.
+232    * @return <jk>true</jk> if the request contains any of the specified query parameters.
+233    */
+234   public boolean containsAnyKeys(String...params) {
+235      for (String p : params)
+236         if (containsKey(p))
+237            return true;
+238      return false;
+239   }
+240
+241   /* Workhorse method */
+242   private <T> T parse(String name, T def, ClassMeta<T> cm) throws ParseException {
+243      String val = getFirst(name);
+244      if (val == null)
+245         return def;
+246      return parseValue(val, cm);
+247   }
+248
+249   /* Workhorse method */
+250   private <T> T parse(String name, ClassMeta<T> cm) throws ParseException {
+251      String val = getFirst(name);
+252      if (cm.isPrimitive() && (val == null || val.isEmpty()))
+253         return cm.getPrimitiveDefault();
+254      return parseValue(val, cm);
+255   }
+256
+257   /* Workhorse method */
+258   @SuppressWarnings("rawtypes")
+259   private <T> T parseAll(String name, ClassMeta<T> cm) throws ParseException {
+260      String[] p = get(name);
+261      if (p == null)
+262         return null;
+263      if (cm.isArray()) {
+264         List c = new ArrayList();
+265         for (int i = 0; i < p.length; i++)
+266            c.add(parseValue(p[i], cm.getElementType()));
+267         return (T)ArrayUtils.toArray(c, cm.getElementType().getInnerClass());
+268      } else if (cm.isCollection()) {
+269         try {
+270            Collection c = (Collection)(cm.canCreateNewInstance() ? cm.newInstance() : new ObjectList());
+271            for (int i = 0; i < p.length; i++)
+272               c.add(parseValue(p[i], cm.getElementType()));
+273            return (T)c;
+274         } catch (ParseException e) {
+275            throw e;
+276         } catch (Exception e) {
+277            // Typically an instantiation exception.
+278            throw new ParseException(e);
+279         }
+280      }
+281      throw new ParseException("Invalid call to getQueryParameters(String, ClassMeta).  Class type must be a Collection or array.");
+282   }
+283
+284   private <T> T parseValue(String val, ClassMeta<T> c) throws ParseException {
+285      return parser.parsePart(val, c);
+286   }
+287}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ +