org.apache.juneau.rest.RestInfoProvider Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.rest;
import java.lang.reflect.Method;
import org.apache.juneau.dto.swagger.*;
import org.apache.juneau.rest.annotation.*;
/**
* REST resource information provider.
*
*
* Provides localized Swagger documentation and other related information about a REST resource.
*
*
See Also:
*
* - {@link RestContext#REST_infoProvider}
*
- {@doc juneau-rest-server.Swagger}
*
*/
public interface RestInfoProvider {
/**
* Represents no RestInfoProvider.
*
*
* Used on annotation to indicate that the value should be inherited from the parent class, and
* ultimately {@link BasicRestInfoProvider} if not specified at any level.
*/
public interface Null extends RestInfoProvider {}
/**
* Returns the localized swagger for the REST resource.
*
*
* This object is made available through the following:
*
* - {@link RestRequest#getSwagger()}
*
*
* @param req The incoming HTTP request.
* @return
* A new {@link Swagger} instance.
*
Never null .
* @throws Exception
* Throw a {@link RestException} with a specific HTTP error status or any other exception
* to cause a SC_INTERNAL_SERVER_ERROR .
*/
public Swagger getSwagger(RestRequest req) throws Exception;
/**
* Returns the localized site name of the REST resource.
*
*
* This object is made available through the following:
*
* - {@link RestRequest#getSiteName()}
*
$RI{siteName} variable.
* $R{siteName} variable.
*
*
* @param req The current request.
* @return The localized site name of the REST resource, or null if none was found.
* @throws Exception
* Throw a {@link RestException} with a specific HTTP error status or any other exception
* to cause a SC_INTERNAL_SERVER_ERROR .
*/
public String getSiteName(RestRequest req) throws Exception;
/**
* Returns the localized title of the REST resource.
*
*
* This object is made available through the following:
*
* - {@link RestRequest#getResourceTitle()}
*
$RI{title} variable.
* $R{resourceTitle} variable.
*
*
* @param req The current request.
* @return The localized title of the REST resource, or null if none was found.
* @throws Exception
* Throw a {@link RestException} with a specific HTTP error status or any other exception
* to cause a SC_INTERNAL_SERVER_ERROR .
*/
public String getTitle(RestRequest req) throws Exception;
/**
* Returns the localized description of the REST resource.
*
*
* This object is made available through the following:
*
* - {@link RestRequest#getResourceDescription()}
*
$RI{description} variable.
* $R{resourceDescription} variable.
*
*
* @param req The current request.
* @return The localized description of the REST resource, or null if none was found.
* @throws Exception
* Throw a {@link RestException} with a specific HTTP error status or any other exception
* to cause a SC_INTERNAL_SERVER_ERROR .
*/
public String getDescription(RestRequest req) throws Exception;
/**
* Returns the localized summary of the specified java method.
*
*
* This object is made available through the following:
*
* - {@link RestRequest#getMethodSummary()}
*
$RI{methodSummary} variable.
* $R{methodSummary} variable.
*
*
* @param method The Java method annotated with {@link RestMethod @RestMethod}.
* @param req The current request.
* @return The localized summary of the method, or null if none was found.
* @throws Exception
* Throw a {@link RestException} with a specific HTTP error status or any other exception
* to cause a SC_INTERNAL_SERVER_ERROR .
*/
public String getMethodSummary(Method method, RestRequest req) throws Exception;
/**
* Returns the localized description of the specified java method on this servlet.
*
*
* This object is made available through the following:
*
* - {@link RestRequest#getMethodDescription()}
*
$RI{methodDescription} variable.
* $R{methodDescription} variable.
*
*
* @param method The Java method annotated with {@link RestMethod @RestMethod}.
* @param req The current request.
* @return The localized description of the method, or null if none was was found.
* @throws Exception
* Throw a {@link RestException} with a specific HTTP error status or any other exception
* to cause a SC_INTERNAL_SERVER_ERROR .
*/
public String getMethodDescription(Method method, RestRequest req) throws Exception;
}