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.Method; 016 017import org.apache.juneau.dto.swagger.*; 018import org.apache.juneau.rest.annotation.*; 019 020/** 021 * REST resource information provider. 022 * 023 * <p> 024 * Provides localized Swagger documentation and other related information about a REST resource. 025 * 026 * <h5 class='section'>See Also:</h5> 027 * <ul> 028 * <li class='jf'>{@link RestContext#REST_infoProvider} 029 * <li class='link'>{@doc juneau-rest-server.Swagger} 030 * </ul> 031 */ 032public interface RestInfoProvider { 033 034 /** 035 * Represents no RestInfoProvider. 036 * 037 * <p> 038 * Used on annotation to indicate that the value should be inherited from the parent class, and 039 * ultimately {@link BasicRestInfoProvider} if not specified at any level. 040 */ 041 public interface Null extends RestInfoProvider {} 042 043 /** 044 * Returns the localized swagger for the REST resource. 045 * 046 * <p> 047 * This object is made available through the following: 048 * <ul> 049 * <li class='jm'>{@link RestRequest#getSwagger()} 050 * </ul> 051 * 052 * @param req The incoming HTTP request. 053 * @return 054 * A new {@link Swagger} instance. 055 * <br>Never <jk>null</jk>. 056 * @throws Exception 057 * Throw a {@link RestException} with a specific HTTP error status or any other exception 058 * to cause a <jsf>SC_INTERNAL_SERVER_ERROR</jsf>. 059 */ 060 public Swagger getSwagger(RestRequest req) throws Exception; 061 062 /** 063 * Returns the localized site name of the REST resource. 064 * 065 * <p> 066 * This object is made available through the following: 067 * <ul> 068 * <li class='jm'>{@link RestRequest#getSiteName()} 069 * <li><code>$RI{siteName}</code> variable. 070 * <li><code>$R{siteName}</code> variable. 071 * </ul> 072 * 073 * @param req The current request. 074 * @return The localized site name of the REST resource, or <jk>null</jk> if none was found. 075 * @throws Exception 076 * Throw a {@link RestException} with a specific HTTP error status or any other exception 077 * to cause a <jsf>SC_INTERNAL_SERVER_ERROR</jsf>. 078 */ 079 public String getSiteName(RestRequest req) throws Exception; 080 081 /** 082 * Returns the localized title of the REST resource. 083 * 084 * <p> 085 * This object is made available through the following: 086 * <ul> 087 * <li class='jm'>{@link RestRequest#getResourceTitle()} 088 * <li><code>$RI{title}</code> variable. 089 * <li><code>$R{resourceTitle}</code> variable. 090 * </ul> 091 * 092 * @param req The current request. 093 * @return The localized title of the REST resource, or <jk>null</jk> if none was found. 094 * @throws Exception 095 * Throw a {@link RestException} with a specific HTTP error status or any other exception 096 * to cause a <jsf>SC_INTERNAL_SERVER_ERROR</jsf>. 097 */ 098 public String getTitle(RestRequest req) throws Exception; 099 100 /** 101 * Returns the localized description of the REST resource. 102 * 103 * <p> 104 * This object is made available through the following: 105 * <ul> 106 * <li class='jm'>{@link RestRequest#getResourceDescription()} 107 * <li><code>$RI{description}</code> variable. 108 * <li><code>$R{resourceDescription}</code> variable. 109 * </ul> 110 * 111 * @param req The current request. 112 * @return The localized description of the REST resource, or <jk>null</jk> if none was found. 113 * @throws Exception 114 * Throw a {@link RestException} with a specific HTTP error status or any other exception 115 * to cause a <jsf>SC_INTERNAL_SERVER_ERROR</jsf>. 116 */ 117 public String getDescription(RestRequest req) throws Exception; 118 119 /** 120 * Returns the localized summary of the specified java method. 121 * 122 * <p> 123 * This object is made available through the following: 124 * <ul> 125 * <li class='jm'>{@link RestRequest#getMethodSummary()} 126 * <li><code>$RI{methodSummary}</code> variable. 127 * <li><code>$R{methodSummary}</code> variable. 128 * </ul> 129 * 130 * @param method The Java method annotated with {@link RestMethod @RestMethod}. 131 * @param req The current request. 132 * @return The localized summary of the method, or <jk>null</jk> if none was found. 133 * @throws Exception 134 * Throw a {@link RestException} with a specific HTTP error status or any other exception 135 * to cause a <jsf>SC_INTERNAL_SERVER_ERROR</jsf>. 136 */ 137 public String getMethodSummary(Method method, RestRequest req) throws Exception; 138 139 /** 140 * Returns the localized description of the specified java method on this servlet. 141 * 142 * <p> 143 * This object is made available through the following: 144 * <ul> 145 * <li class='jm'>{@link RestRequest#getMethodDescription()} 146 * <li><code>$RI{methodDescription}</code> variable. 147 * <li><code>$R{methodDescription}</code> variable. 148 * </ul> 149 * 150 * @param method The Java method annotated with {@link RestMethod @RestMethod}. 151 * @param req The current request. 152 * @return The localized description of the method, or <jk>null</jk> if none was was found. 153 * @throws Exception 154 * Throw a {@link RestException} with a specific HTTP error status or any other exception 155 * to cause a <jsf>SC_INTERNAL_SERVER_ERROR</jsf>. 156 */ 157 public String getMethodDescription(Method method, RestRequest req) throws Exception; 158}