org.msgpack.value.Value Maven / Gradle / Ivy
Show all versions of msgpack-core Show documentation
//
// MessagePack for Java
//
// Licensed 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.msgpack.value;
import org.msgpack.core.MessagePacker;
import java.io.IOException;
/**
* Value stores a value and its type in MessagePack type system.
*
* Type conversion
*
* You can check type first using isXxx() methods or {@link #getValueType()} method, then convert the value to a
* subtype using asXxx() methods. You can also call asXxx() methods directly and catch
* {@link org.msgpack.core.MessageTypeCastException}.
*
*
* MessagePack type Check method Convert method Value type Nil {@link #isNilValue()} {@link #asNumberValue()} {@link NilValue} Boolean {@link #isBooleanValue()} {@link #asBooleanValue()} {@link BooleanValue} Integer or Float {@link #isNumberValue()} {@link #asNumberValue()} {@link NumberValue} Integer {@link #isIntegerValue()} {@link #asIntegerValue()} {@link IntegerValue} Float {@link #isFloatValue()} {@link #asFloatValue()} {@link FloatValue} String or Binary {@link #isRawValue()} {@link #asRawValue()} {@link RawValue} String {@link #isStringValue()} {@link #asStringValue()} {@link StringValue} Binary {@link #isBinaryValue()} {@link #asBinaryValue()} {@link BinaryValue} Array {@link #isArrayValue()} {@link #asArrayValue()} {@link ArrayValue} Map {@link #isMapValue()} {@link #asMapValue()} {@link MapValue} Extension {@link #isExtensionValue()} {@link #asExtensionValue()} {@link ExtensionValue}
*
* Immutable interface
*
* Value interface is the base interface of all Value interfaces. Immutable subtypes are useful so that you can
* declare that a (final) field or elements of a container object are immutable. Method arguments should be a
* regular Value interface generally.
*
* You can use {@link #immutableValue()} method to get immutable subtypes.
*
*
* MessagePack type Subtype method Immutable value type any types {@link Value}.{@link Value#immutableValue()} {@link ImmutableValue} Nil {@link NilValue}.{@link NilValue#immutableValue()} {@link ImmutableNilValue} Boolean {@link BooleanValue}.{@link BooleanValue#immutableValue()} {@link ImmutableBooleanValue} Integer {@link IntegerValue}.{@link IntegerValue#immutableValue()} {@link ImmutableIntegerValue} Float {@link FloatValue}.{@link FloatValue#immutableValue()} {@link ImmutableFloatValue} Integer or Float {@link NumberValue}.{@link NumberValue#immutableValue()} {@link ImmutableNumberValue} String or Binary {@link RawValue}.{@link RawValue#immutableValue()} {@link ImmutableRawValue} String {@link StringValue}.{@link StringValue#immutableValue()} {@link ImmutableStringValue} Binary {@link BinaryValue}.{@link BinaryValue#immutableValue()} {@link ImmutableBinaryValue} Array {@link ArrayValue}.{@link ArrayValue#immutableValue()} {@link ImmutableArrayValue} Map {@link MapValue}.{@link MapValue#immutableValue()} {@link ImmutableMapValue} Extension {@link ExtensionValue}.{@link ExtensionValue#immutableValue()} {@link ImmutableExtensionValue}
*
* Converting to JSON
*
* {@link #toJson()} method returns JSON representation of a Value. See its documents for details.
*
* toString() also returns a string representation of a Value that is similar to JSON. However, unlike toJson() method,
* toString() may return a special format that is not be compatible with JSON when JSON doesn't support the type such
* as ExtensionValue.
*/
public interface Value
{
/**
* Returns type of this value.
*
* Note that you can't use instanceof to check type of a value because type of a mutable value is variable.
*/
ValueType getValueType();
/**
* Returns immutable copy of this value.
*
* This method simply returns this without copying the value if this value is already immutable.
*/
ImmutableValue immutableValue();
/**
* Returns true if type of this value is Nil.
*
* If this method returns true, {@code asNilValue} never throws exceptions.
* Note that you can't use instanceof or cast ((NilValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isNilValue();
/**
* Returns true if type of this value is Boolean.
*
* If this method returns true, {@code asBooleanValue} never throws exceptions.
* Note that you can't use instanceof or cast ((BooleanValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isBooleanValue();
/**
* Returns true if type of this value is Integer or Float.
*
* If this method returns true, {@code asNumberValue} never throws exceptions.
* Note that you can't use instanceof or cast ((NumberValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isNumberValue();
/**
* Returns true if type of this value is Integer.
*
* If this method returns true, {@code asIntegerValue} never throws exceptions.
* Note that you can't use instanceof or cast ((IntegerValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isIntegerValue();
/**
* Returns true if type of this value is Float.
*
* If this method returns true, {@code asFloatValue} never throws exceptions.
* Note that you can't use instanceof or cast ((FloatValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isFloatValue();
/**
* Returns true if type of this value is String or Binary.
*
* If this method returns true, {@code asRawValue} never throws exceptions.
* Note that you can't use instanceof or cast ((RawValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isRawValue();
/**
* Returns true if type of this value is Binary.
*
* If this method returns true, {@code asBinaryValue} never throws exceptions.
* Note that you can't use instanceof or cast ((BinaryValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isBinaryValue();
/**
* Returns true if type of this value is String.
*
* If this method returns true, {@code asStringValue} never throws exceptions.
* Note that you can't use instanceof or cast ((StringValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isStringValue();
/**
* Returns true if type of this value is Array.
*
* If this method returns true, {@code asArrayValue} never throws exceptions.
* Note that you can't use instanceof or cast ((ArrayValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isArrayValue();
/**
* Returns true if type of this value is Map.
*
* If this method returns true, {@code asMapValue} never throws exceptions.
* Note that you can't use instanceof or cast ((MapValue) thisValue) to check type of a value because type of a mutable value is variable.
*/
boolean isMapValue();
/**
* Returns true if type of this an Extension.
*
* If this method returns true, {@code asExtensionValue} never throws exceptions.
* Note that you can't use instanceof or cast ((ExtensionValue) thisValue) to check type of a value because
* type of a mutable value is variable.
*/
boolean isExtensionValue();
/**
* Returns the value as {@code NilValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((NilValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Nil.
*/
NilValue asNilValue();
/**
* Returns the value as {@code BooleanValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((BooleanValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Boolean.
*/
BooleanValue asBooleanValue();
/**
* Returns the value as {@code NumberValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((NumberValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Integer or Float.
*/
NumberValue asNumberValue();
/**
* Returns the value as {@code IntegerValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((IntegerValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Integer.
*/
IntegerValue asIntegerValue();
/**
* Returns the value as {@code FloatValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((FloatValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Float.
*/
FloatValue asFloatValue();
/**
* Returns the value as {@code RawValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((RawValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Binary or String.
*/
RawValue asRawValue();
/**
* Returns the value as {@code BinaryValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((BinaryValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Binary.
*/
BinaryValue asBinaryValue();
/**
* Returns the value as {@code StringValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((StringValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not String.
*/
StringValue asStringValue();
/**
* Returns the value as {@code ArrayValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((ArrayValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Array.
*/
ArrayValue asArrayValue();
/**
* Returns the value as {@code MapValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((MapValue) thisValue) to check type of a value because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not Map.
*/
MapValue asMapValue();
/**
* Returns the value as {@code ExtensionValue}. Otherwise throws {@code MessageTypeCastException}.
*
* Note that you can't use instanceof or cast ((ExtensionValue) thisValue) to check type of a value
* because type of a mutable value is variable.
*
* @throws MessageTypeCastException If type of this value is not an Extension.
*/
ExtensionValue asExtensionValue();
/**
* Serializes the value using the specified {@code MessagePacker}
*
* @see MessagePacker
*/
void writeTo(MessagePacker pk)
throws IOException;
/**
* Compares this value to the specified object.
*
* This method returns {@code true} if type and value are equivalent.
* If this value is {@code MapValue} or {@code ArrayValue}, this method check equivalence of elements recursively.
*/
boolean equals(Object obj);
/**
* Returns json representation of this Value.
*
* Following behavior is not configurable at this release and they might be changed at future releases:
*
*
* - if a key of MapValue is not string, the key is converted to a string using toString method.
* - NaN and Infinity of DoubleValue are converted to null.
* - ExtensionValue is converted to a 2-element array where first element is a number and second element is the data encoded in hex.
* - BinaryValue is converted to a string using UTF-8 encoding. Invalid byte sequence is replaced with
U+FFFD replacement character.
* - Invalid UTF-8 byte sequences in StringValue is replaced with
U+FFFD replacement character
*
*/
String toJson();
}