jakarta.ws.rs.core.Variant Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jaxrs-ri Show documentation
Show all versions of jaxrs-ri Show documentation
A bundle project producing JAX-RS RI bundles. The primary artifact is an "all-in-one" OSGi-fied JAX-RS RI bundle
(jaxrs-ri.jar).
Attached to that are two compressed JAX-RS RI archives. The first archive (jaxrs-ri.zip) consists of binary RI bits and
contains the API jar (under "api" directory), RI libraries (under "lib" directory) as well as all external
RI dependencies (under "ext" directory). The secondary archive (jaxrs-ri-src.zip) contains buildable JAX-RS RI source
bundle and contains the API jar (under "api" directory), RI sources (under "src" directory) as well as all external
RI dependencies (under "ext" directory). The second archive also contains "build.xml" ANT script that builds the RI
sources. To build the JAX-RS RI simply unzip the archive, cd to the created jaxrs-ri directory and invoke "ant" from
the command line.
/*
* Copyright (c) 2010, 2019 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.ws.rs.core;
import java.io.StringWriter;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import jakarta.ws.rs.ext.RuntimeDelegate;
/**
* Abstraction for a resource representation variant.
*
* Contains information about media type, language and encoding of the resource representation.
*
* @author Paul Sandoz
* @author Marc Hadley
* @since 1.0
*/
public class Variant {
private Locale language;
private MediaType mediaType;
private String encoding;
/**
* Create a new instance of Variant.
*
* @param mediaType the media type of the variant - may be {@code null}.
* @param language the language of the variant (two-letter ISO-639 code); may be {@code null}.
* @param encoding the content encoding of the variant - may be {@code null}.
* @throws java.lang.IllegalArgumentException if all the parameters are {@code null}.
* @since 2.0
*/
public Variant(final MediaType mediaType, final String language, final String encoding) {
if (mediaType == null && language == null && encoding == null) {
throw new IllegalArgumentException("mediaType, language, encoding all null");
}
this.encoding = encoding;
this.language = (language == null) ? null : new Locale(language);
this.mediaType = mediaType;
}
/**
* Create a new instance of Variant.
*
* @param mediaType the media type of the variant - may be {@code null}.
* @param language the language of the variant (two-letter ISO-639 code); may be {@code null}.
* @param country uppercase two-letter ISO-3166 language code of the variant; may be {@code null} provided
* {@code language} is {@code null} too.
* @param encoding the content encoding of the variant - may be {@code null}.
* @throws java.lang.IllegalArgumentException if all the parameters are {@code null}.
* @since 2.0
*/
public Variant(final MediaType mediaType, final String language, final String country, final String encoding) {
if (mediaType == null && language == null && encoding == null) {
throw new IllegalArgumentException("mediaType, language, encoding all null");
}
this.encoding = encoding;
this.language = (language == null) ? null : new Locale(language, country);
this.mediaType = mediaType;
}
/**
* Create a new instance of Variant.
*
* @param mediaType the media type of the variant - may be {@code null}.
* @param language the language of the variant (two-letter ISO-639 code); may be {@code null}.
* @param country uppercase two-letter ISO-3166 language code of the variant; may be {@code null} provided
* {@code language} is {@code null} too.
* @param languageVariant vendor and browser specific language code of the variant (see also {@link Locale} class
* description); may be {@code null} provided {@code language} and {@code country} are {@code null} too.
* @param encoding the content encoding of the variant - may be {@code null}.
* @throws java.lang.IllegalArgumentException if all the parameters are {@code null}.
* @since 2.0
*/
public Variant(final MediaType mediaType, final String language, final String country, final String languageVariant, final String encoding) {
if (mediaType == null && language == null && encoding == null) {
throw new IllegalArgumentException("mediaType, language, encoding all null");
}
this.encoding = encoding;
this.language = (language == null) ? null : new Locale(language, country, languageVariant);
this.mediaType = mediaType;
}
/**
* Create a new instance of Variant.
*
* @param mediaType the media type of the variant - may be {@code null}.
* @param language the language of the variant - may be {@code null}.
* @param encoding the content encoding of the variant - may be {@code null}.
* @throws java.lang.IllegalArgumentException if all the parameters are {@code null}.
*/
public Variant(final MediaType mediaType, final Locale language, final String encoding) {
if (mediaType == null && language == null && encoding == null) {
throw new IllegalArgumentException("mediaType, language, encoding all null");
}
this.encoding = encoding;
this.language = language;
this.mediaType = mediaType;
}
/**
* Get the language of the variant.
*
* @return the language or {@code null} if none set.
*/
public Locale getLanguage() {
return language;
}
/**
* Get the string representation of the variant language, or {@code null} if no language has been set.
*
* @return the string representing variant language or {@code null} if none set.
* @since 2.0
*/
public String getLanguageString() {
return (language == null) ? null : language.toString();
}
/**
* Get the media type of the variant.
*
* @return the media type or {@code null} if none set.
*/
public MediaType getMediaType() {
return mediaType;
}
/**
* Get the encoding of the variant.
*
* @return the encoding or {@code null} if none set.
*/
public String getEncoding() {
return encoding;
}
/**
* Create a {@link VariantListBuilder} initialized with a set of supported media types.
*
* @param mediaTypes the available mediaTypes. If specific char-sets are supported they should be included as parameters
* of the respective media type.
* @return the initialized builder.
* @throws java.lang.IllegalArgumentException if mediaTypes is null or contains no elements.
*/
public static VariantListBuilder mediaTypes(final MediaType... mediaTypes) {
VariantListBuilder b = VariantListBuilder.newInstance();
b.mediaTypes(mediaTypes);
return b;
}
/**
* Create a {@link VariantListBuilder} initialized with a set of supported languages.
*
* @param languages the available languages.
* @return the initialized builder.
* @throws java.lang.IllegalArgumentException if languages is null or contains no elements.
*/
public static VariantListBuilder languages(final Locale... languages) {
VariantListBuilder b = VariantListBuilder.newInstance();
b.languages(languages);
return b;
}
/**
* Create a {@link VariantListBuilder} initialized with a set of supported encodings.
*
* @param encodings the available encodings.
* @return the initialized builder.
* @throws java.lang.IllegalArgumentException if encodings is null or contains no elements.
*/
public static VariantListBuilder encodings(final String... encodings) {
VariantListBuilder b = VariantListBuilder.newInstance();
b.encodings(encodings);
return b;
}
/**
* Generate hash code from variant properties.
*
* @return the hash code.
*/
@Override
public int hashCode() {
return Objects.hash(this.language, this.mediaType, this.encoding);
}
/**
* Compares obj to this variant to see if they are the same considering all property values.
*
* @param obj the object to compare to.
* @return true if the two variants are the same, false otherwise.
*/
@Override
public boolean equals(final Object obj) {
if (obj == null) {
return false;
}
if (getClass() != obj.getClass()) {
return false;
}
final Variant other = (Variant) obj;
if (!Objects.equals(this.language, other.language)) {
return false;
}
if (!Objects.equals(this.mediaType, other.mediaType)) {
return false;
}
return Objects.equals(this.encoding, other.encoding);
}
@Override
public String toString() {
StringWriter w = new StringWriter();
w.append("Variant[mediaType=");
w.append(mediaType == null ? "null" : mediaType.toString());
w.append(", language=");
w.append(language == null ? "null" : language.toString());
w.append(", encoding=");
w.append(encoding == null ? "null" : encoding);
w.append("]");
return w.toString();
}
/**
* A builder for a list of representation variants.
*/
public abstract static class VariantListBuilder {
/**
* Protected constructor, use the static {@code newInstance} method to obtain an instance.
*/
protected VariantListBuilder() {
}
/**
* Create a new builder instance.
*
* @return a new builder instance.
*/
public static VariantListBuilder newInstance() {
return RuntimeDelegate.getInstance().createVariantListBuilder();
}
/**
* Add the current combination of metadata to the list of supported variants (provided the current combination of
* metadata is not empty) and build a list of representation variants from the current state of the builder. After this
* method is called the builder is reset to an empty state.
*
* @return a list of representation variants.
*/
public abstract List build();
/**
* Add the current combination of metadata to the list of supported variants, after this method is called the current
* combination of metadata is emptied.
*
* If more than one value is supplied for one or more of the variant properties then a variant will be generated for
* each possible combination. E.g. in the following {@code list} would have five (4 + 1) members:
*
*
*
* List<Variant> list = VariantListBuilder.newInstance()
* .languages(Locale.ENGLISH, Locale.FRENCH).encodings("zip", "identity").add()
* .languages(Locale.GERMAN).mediaTypes(MediaType.TEXT_PLAIN_TYPE).add()
* .build()
*
*
* Note that it is not necessary to call the {@code add()} method immediately before the build method is called. E.g.
* the resulting list produced in the example above would be identical to the list produced by the following code:
*
*
*
* List<Variant> list = VariantListBuilder.newInstance()
* .languages(Locale.ENGLISH, Locale.FRENCH).encodings("zip", "identity").add()
* .languages(Locale.GERMAN).mediaTypes(MediaType.TEXT_PLAIN_TYPE)
* .build()
*
*
* @return the updated builder.
* @throws IllegalStateException if there is not at least one mediaType, language or encoding set for the current
* variant.
*/
public abstract VariantListBuilder add();
/**
* Set the language(s) for this variant.
*
* @param languages the available languages.
* @return the updated builder.
*/
public abstract VariantListBuilder languages(Locale... languages);
/**
* Set the encoding(s) for this variant.
*
* @param encodings the available encodings.
* @return the updated builder.
*/
public abstract VariantListBuilder encodings(String... encodings);
/**
* Set the media type(s) for this variant.
*
* @param mediaTypes the available mediaTypes. If specific charsets are supported they should be included as parameters
* of the respective media type.
* @return the updated builder.
*/
public abstract VariantListBuilder mediaTypes(MediaType... mediaTypes);
}
}