001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.beans;
018
019import java.util.*;
020
021import org.apache.juneau.commons.*;
022import org.apache.juneau.commons.bean.*;
023import org.apache.juneau.http.*;
024import org.apache.juneau.marshall.html.*;
025
026/**
027 * Describes a single route (an {@code @RestOp}-annotated method) in a route-index listing.
028 *
029 * <p>
030 * Companion of {@link ResourceDescription} (which describes a child resource); a {@code RouteDescription}
031 * describes an operation mounted on a resource.  Returned (as a {@link RouteDescriptions} list) by the
032 * route-index op so the response is content-negotiated through the configured serializers &mdash; an
033 * {@code Accept: text/html} request renders a browsable table with the {@linkplain #getPath() path} as a
034 * clickable link (via {@link Html#link() @Html(link)}), while {@code application/json} / {@code text/xml}
035 * clients receive the same entries in their requested format.
036 *
037 * <p>
038 * The five serialized properties &mdash; {@code path}, {@code methods}, {@code summary}, {@code description},
039 * and {@code deprecated} &mdash; preserve the JSON shape emitted by earlier route-index snapshots so existing
040 * API clients see an equivalent payload.
041 *
042 * <h5 class='section'>See Also:</h5><ul>
043 *    <li class='jc'>{@link RouteDescriptions}
044 *    <li class='jc'>{@link ResourceDescription}
045 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/UtilityBeans">Utility Beans</a>
046 * </ul>
047 *
048 * @serial exclude
049 * @since 10.0.0
050 */
051@BeanType(properties = "path,methods,summary,description,deprecated", findFluentSetters = true)
052@Response(schema = @Schema(ignore = true))
053public class RouteDescription {
054
055   private String path;
056   private List<String> methods;
057   private String summary;
058   private String description;
059   private boolean deprecated;
060
061   /** No-arg bean constructor. */
062   public RouteDescription() {}
063
064   /**
065    * Constructor.
066    *
067    * @param path The mount path of the operation (e.g. {@code "/items/{id}"}).
068    * @param methods The HTTP methods the operation responds to (e.g. {@code ["GET"]}).
069    * @param summary The operation summary, or an empty string when none is declared.
070    * @param description The operation description, or an empty string when none is declared.
071    * @param deprecated Whether the operation (or its declaring class) is {@link Deprecated @Deprecated}.
072    */
073   public RouteDescription(String path, List<String> methods, String summary, String description, boolean deprecated) {
074      this.path = path;
075      this.methods = methods;
076      this.summary = summary;
077      this.description = description;
078      this.deprecated = deprecated;
079   }
080
081   /**
082    * Returns the mount path of the operation.
083    *
084    * <p>
085    * Rendered as a clickable link in HTML output via {@link Html#link() @Html(link)}.
086    *
087    * @return The mount path.
088    */
089   @Html(link = "servlet:{path}")
090   public String getPath() { return path; }
091
092   /**
093    * Sets the mount path of the operation.
094    *
095    * @param value The new value.
096    * @return This object.
097    */
098   public RouteDescription path(String value) {
099      path = value;
100      return this;
101   }
102
103   /**
104    * Returns the HTTP methods the operation responds to.
105    *
106    * @return The HTTP methods.
107    */
108   public List<String> getMethods() { return methods; }
109
110   /**
111    * Sets the HTTP methods the operation responds to.
112    *
113    * @param value The new value.
114    * @return This object.
115    */
116   public RouteDescription methods(List<String> value) {
117      methods = value;
118      return this;
119   }
120
121   /**
122    * Returns the operation summary.
123    *
124    * @return The summary, or an empty string when none is declared.
125    */
126   public String getSummary() { return summary; }
127
128   /**
129    * Sets the operation summary.
130    *
131    * @param value The new value.
132    * @return This object.
133    */
134   public RouteDescription summary(String value) {
135      summary = value;
136      return this;
137   }
138
139   /**
140    * Returns the operation description.
141    *
142    * @return The description, or an empty string when none is declared.
143    */
144   public String getDescription() { return description; }
145
146   /**
147    * Sets the operation description.
148    *
149    * @param value The new value.
150    * @return This object.
151    */
152   public RouteDescription description(String value) {
153      description = value;
154      return this;
155   }
156
157   /**
158    * Returns whether the operation is deprecated.
159    *
160    * @return <jk>true</jk> if the operation (or its declaring class) is {@link Deprecated @Deprecated}.
161    */
162   public boolean isDeprecated() { return deprecated; }
163
164   /**
165    * Sets whether the operation is deprecated.
166    *
167    * @param value The new value.
168    * @return This object.
169    */
170   public RouteDescription deprecated(boolean value) {
171      deprecated = value;
172      return this;
173   }
174}