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