add documentation for RequestLanguageResolver
@@ -9,6 +9,9 @@ import java.util.List;
import java.util.Locale;
import java.util.Set;
+/**
+ * Resolver for the response language for a web request.
+ */
@AllArgsConstructor
public class RequestLanguageResolver {
static final String ACCEPT_LANGUAGE_HEADER = "Accept-Language";
@@ -16,6 +19,17 @@ public class RequestLanguageResolver {
private final Set<String> supportedLanguages;
+ /**
+ * Get the language to use for the response to the given request.
+ *
+ * @param webRequest Incoming HTTP request.
+ * @return Language to be used in the response.
+ * @throws BadRequestException The language in the request parameter is unknown.
+ *
+ * The function first checks for a 'lang' query parameter. If this is not given, it looks for
+ * an Accept-Language header and tries to find a supported language there. If that does not
+ * work either, the default language is returned
+ */
public String resolveRequestedLanguage(Request webRequest) throws BadRequestException {
String language = webRequest.queryParams("lang");
if (StringUtils.isBlank(language)) {
@@ -23,12 +37,18 @@ public class RequestLanguageResolver {
if (StringUtils.isBlank(language))
language = DEFAULT_LANGUAGE;
} else {
- isLanguageSupported(language);
+ checkLanguageSupported(language);
}
return language;
}
+ /**
+ * Look for a language parameter in the request headers.
+ *
+ * @param webRequest Incoming HTTP request.
+ * @return A suitable language header or <b>null</b> if not could be found.
+ */
private String fallbackLanguageFromHeaders(Request webRequest) {
String acceptLanguageHeader = webRequest.headers(ACCEPT_LANGUAGE_HEADER);
if (StringUtils.isBlank(acceptLanguageHeader))
@@ -44,7 +64,13 @@ public class RequestLanguageResolver {
return null;
}
- private void isLanguageSupported(String lang) throws BadRequestException {
+ /**
+ * Check that the language is a supported one.
+ *
+ * @param lang Language to use.
+ * @throws BadRequestException The language is not in the list of supported languages.
+ */
+ private void checkLanguageSupported(String lang) throws BadRequestException {
if (!supportedLanguages.contains((lang))) {
throw new BadRequestException(400, "language " + lang + " is not supported, supported languages are: " + Joiner.on(", ").join(supportedLanguages));
}
