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