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 static org.apache.juneau.commons.utils.ThrowableUtils.*;
020
021import org.apache.juneau.rest.server.*;
022
023/**
024 * A POJO structure that describes the list of child resources associated with a resource.
025 *
026 * <p>
027 * Typically used in top-level GET methods of router resources to render a list of available child resources.
028 *
029 * <h2 class='section'>See Also:</h2><ul>
030 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/UtilityBeans">Utility Beans</a>
031 *    <li class='jc'>{@link org.apache.juneau.rest.server.servlet.BasicRestServletGroup}
032 * </ul>
033 *
034 * @serial exclude
035 */
036public class ChildResourceDescriptions extends ResourceDescriptions {
037   private static final long serialVersionUID = 1L;
038
039   /**
040    * Static creator.
041    *
042    * @param req The HTTP servlet request.
043    *    <br>Must not be <jk>null</jk>.
044    * @return A new {@link ChildResourceDescriptions} bean.
045    */
046   public static ChildResourceDescriptions of(RestRequest req) {
047      return new ChildResourceDescriptions(req);
048   }
049
050   /**
051    * Bean constructor.
052    */
053   public ChildResourceDescriptions() {}
054
055   /**
056    * Constructor.
057    *
058    * @param context The servlet context that this bean describes.
059    *    <br>Must not be <jk>null</jk>.
060    * @param req The HTTP servlet request.
061    */
062   public ChildResourceDescriptions(RestContext context, RestRequest req) {
063      this(context, req, false);
064   }
065
066   /**
067    * Constructor.
068    *
069    * @param context The servlet context that this bean describes.
070    *    <br>Must not be <jk>null</jk>.
071    * @param req The HTTP servlet request.
072    * @param sort
073    *    If <jk>true</jk>, list will be ordered by name alphabetically.
074    *    Default is to maintain the order as specified in the annotation.
075    */
076   @SuppressWarnings({
077      "javabugs:S2259" // The RestChildren bean is registered during context initialization and is always present once a request is served.
078   })
079   public ChildResourceDescriptions(RestContext context, RestRequest req, boolean sort) {
080      for (var e : context.getRestChildren().asMap().entrySet()) {
081         String title = null;
082         try {
083            title = e.getValue().getSwagger(req.getLocale()).map(x -> x == null ? null : x.getInfo()).map(x -> x == null ? null : x.getTitle()).orElse(null);
084         } catch (Exception e1) {
085            title = localizedMessage(e1);
086         }
087         add(new ResourceDescription(e.getKey(), title));
088      }
089      if (sort)
090         this.sort(null);
091   }
092
093   /**
094    * Constructor.
095    *
096    * @param req The HTTP servlet request.
097    *    <br>Must not be <jk>null</jk>.
098    */
099   public ChildResourceDescriptions(RestRequest req) {
100      this(req.getContext(), req, false);
101   }
102
103   @Override /* Overridden from ResourceDescriptions */
104   public ChildResourceDescriptions append(String name, String description) {
105      super.append(name, description);
106      return this;
107   }
108
109   @Override /* Overridden from ResourceDescriptions */
110   public ChildResourceDescriptions append(String name, String uri, String description) {
111      super.append(name, uri, description);
112      return this;
113   }
114}