com.restfb.Parameter Maven / Gradle / Ivy
Show all versions of restfb Show documentation
/*
* Copyright (c) 2010-2024 Mark Allen, Norbert Bartels.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package com.restfb;
import static com.restfb.util.StringUtils.isBlank;
import static com.restfb.util.StringUtils.trimToEmpty;
import static java.lang.String.format;
import java.util.Locale;
import java.util.Optional;
import com.restfb.exception.FacebookJsonMappingException;
/**
* Representation of a Facebook API request parameter.
*
* @author Mark Allen
*/
public final class Parameter {
/**
* Parameter name.
*/
public final String name;
/**
* Parameter value.
*/
public final String value;
/**
* Creates a new parameter with the given {@code name} and {@code value}.
*
* @param name
* The parameter name.
* @param value
* The parameter value.
* @param jsonMapper
* Mapper for converting the parameter value to JSON.
* @throws IllegalArgumentException
* If {@code name} is {@code null} or a blank string or either {@code value} or {@code jsonMapper} is
* {@code null}.
*/
private Parameter(String name, Object value, JsonMapper jsonMapper) {
if (isBlank(name) || value == null) {
throw new IllegalArgumentException(Parameter.class + " instances must have a non-blank name and non-null value."
+ " Got instead name:" + name + ", value:" + value);
}
this.value = Optional.ofNullable(jsonMapper)
.orElseThrow(() -> new IllegalArgumentException("Provided " + JsonMapper.class + " must not be null."))
.toJson(value, true);
this.name = trimToEmpty(name);
}
/**
* Factory method which provides an instance with the given {@code name} and {@code value}.
*
* The {@code value} parameter is often a {@link String} or primitive type like {@link Integer}, but you may pass in a
* {@link java.util.List}, {@link java.util.Map}, or your own @Facebook-annotated Javabean, and it will be
* converted to JSON automatically. See the "attachment" section of
* the stream.publish API documentation for
* an example of where this is useful.
*
* @param name
* The parameter name.
* @param value
* The parameter value.
* @return A {@code Parameter} instance with the given {@code name} and {@code value}.
* @throws IllegalArgumentException
* If {@code name} or {@code value} is {@code null} or a blank string.
* @throws FacebookJsonMappingException
* If an error occurs when converting {@code value} to JSON.
*/
public static Parameter with(String name, Object value) {
return Parameter.with(name, value, new DefaultJsonMapper());
}
/**
* convenience factory method which needs a comma separated list of fields that the dev likes to fetch from the API
*
* @param fieldList
* comma separated list of fields
* @return Parameter object
*/
public static Parameter withFields(String fieldList) {
return Parameter.with("fields", fieldList);
}
/**
* Convenience factory method that creates a {@code Parameter} object to retrieve the metadata from the API.
*
* @return Parameter object
*/
public static Parameter withMetadata() {
return Parameter.with("metadata", "1");
}
/**
* convenience factory method which creates a {@code Parameter} object to fetch data from API with given locale
*
* @param locale
* the locale that should be used to fetch the data
*
* @return Parameter object
*/
public static Parameter withLocale(Locale locale) {
return Parameter.with("locale", locale.getLanguage());
}
/**
* convenience factory method which creates a {@code Parameter} object to fetch data from API with given limit
*
* @param limit
* the limit that should be used fetching data
*
* @return Parameter object
*/
public static Parameter withLimit(int limit) {
return Parameter.with("limit", limit);
}
/**
* convenience factory method which creates a {@code Parameter} object to post an object with a message parameter to
* the API
*
* @param obj
* The content of the message, should be a String, but maybe some JSON
*
* @return Parameter object
*/
public static Parameter withMessage(Object obj) {
return Parameter.with("message", obj);
}
/**
* convenience factory method which creates a {@code Parameter} object to query some information e.g. searching profiles
* the API
*
* @param queryString
* the String used in the query
*
* @return Parameter object
*/
public static Parameter withQuery(String queryString) {
return Parameter.with("q", queryString);
}
/**
* Factory method which provides an instance with the given {@code name} and {@code value}, using the provided
* {@code jsonMapper} to turn {@code value} into a JSON string.
*
* The {@code value} parameter is often a {@link String} or primitive type like {@link Integer}, but you may pass in a
* {@link java.util.List}, {@link java.util.Map}, or your own @Facebook-annotated Javabean, and it will be
* converted to JSON automatically. See the "attachment" section of
* the stream.publish API documentation for
* an example of where this is useful.
*
* @param name
* The parameter name.
* @param value
* The parameter value.
* @param jsonMapper
* The jsonMapper
* @return A {@code Parameter} instance with the given {@code name} and {@code value}.
* @throws IllegalArgumentException
* If {@code name} or {@code value} is {@code null} or a blank string.
* @throws FacebookJsonMappingException
* If an error occurs when converting {@code value} to JSON.
*/
public static Parameter with(String name, Object value, JsonMapper jsonMapper) {
return new Parameter(name, value, jsonMapper);
}
/**
* @see java.lang.Object#equals(java.lang.Object)
*/
@Override
public boolean equals(Object obj) {
if (obj == null) {
return false;
}
if (!getClass().equals(obj.getClass())) {
return false;
}
Parameter other = (Parameter) obj;
if (this.name != other.name && !this.name.equals(other.name)) {
return false;
}
return !(this.value != other.value && !this.value.equals(other.value));
}
@Override
public int hashCode() {
int hash = 7;
hash = 37 * hash + this.name.hashCode();
hash = 41 * hash + this.value.hashCode();
return hash;
}
@Override
public String toString() {
return format("Parameter[%s=%s]", name, value);
}
}