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.httppart;
014
015import static org.apache.juneau.common.internal.StringUtils.*;
016import static org.apache.juneau.internal.CollectionUtils.*;
017
018import java.util.*;
019
020import org.apache.juneau.http.response.*;
021import org.apache.juneau.rest.*;
022
023/**
024 * Represents a single request attribute on an HTTP request.
025 *
026 * <p>
027 * Typically accessed through the {@link RequestAttributes} class.
028 *
029 * <p>
030 *    Some important methods on this class are:
031 * </p>
032 * <ul class='javatree'>
033 *    <li class='jc'>{@link RequestAttribute}
034 *    <ul class='spaced-list'>
035 *       <li>Methods for retrieving simple string values:
036 *       <ul class='javatreec'>
037 *          <li class='jm'>{@link RequestAttribute#asString() asString()}
038 *          <li class='jm'>{@link RequestAttribute#get() get()}
039 *          <li class='jm'>{@link RequestAttribute#isPresent() isPresent()}
040 *          <li class='jm'>{@link RequestAttribute#orElse(Object) orElse(Object)}
041 *       </ul>
042 *       <li>Methods for retrieving as custom types:
043 *       <ul class='javatreec'>
044 *          <li class='jm'>{@link RequestAttribute#as(Class) as(Class)}
045 *       </ul>
046 *       <li>Methods for performing assertion checks:
047 *       <ul class='javatreec'>
048 *          <li class='jm'>{@link RequestAttribute#assertName() assertName()}
049 *          <li class='jm'>{@link RequestAttribute#assertValue() assertValue()}
050 *       </ul>
051 *       <li>Other methods:
052 *       <ul class='javatreec'>
053 *          <li class='jm'>{@link RequestAttribute#getName() getName()}
054 *          <li class='jm'>{@link RequestAttribute#getValue() getValue()}
055*     </ul>
056 * </ul>
057 *
058 * <h5 class='section'>See Also:</h5><ul>
059 *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.HttpParts">HTTP Parts</a>
060 * </ul>
061 */
062public class RequestAttribute extends BasicNamedAttribute {
063
064   private final RestRequest req;
065
066   /**
067    * Constructor.
068    *
069    * @param request The request object.
070    * @param name The parameter name.
071    * @param value The parameter value.
072    */
073   public RequestAttribute(RestRequest request, String name, Object value) {
074      super(name, value);
075      this.req = request;
076   }
077
078   //------------------------------------------------------------------------------------------------------------------
079   // Retrievers
080   //------------------------------------------------------------------------------------------------------------------
081
082   /**
083    * Returns the value of this part as a string.
084    *
085    * @return The value of this part as a string, or {@link Optional#empty()} if the part was not present.
086    */
087   public Optional<String> asString() {
088      return optional(stringify(getValue()));
089   }
090
091   /**
092    * Converts this part to the specified POJO.
093    *
094    * @param <T> The type to convert to.
095    * @param type The type to convert to.
096    * @return The converted type, or {@link Optional#empty()} if the part is not present.
097    * @throws BasicHttpException If value could not be parsed.
098    */
099   public <T> Optional<T> as(Class<T> type) {
100      return optional(req.getBeanSession().convertToType(getValue(), type));
101   }
102}