• Home
• org.pkl-lang
• pkl-tools
• 0.27.0
• source code
• Value.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.pkl.thirdparty.msgpack.value.Value Maven / Gradle / Ivy

//
// 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.pkl.thirdparty.msgpack.value;

import org.pkl.thirdparty.msgpack.core.MessagePacker;
import org.pkl.thirdparty.msgpack.core.MessageTypeCastException;

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.pkl.thirdparty.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 true if the type of this value is Timestamp.
     *
     * If this method returns true, {@code asTimestamp} 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 isTimestampValue();

    /**
     * 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();

    /**
     * Returns the value as {@code TimestampValue}. Otherwise throws {@code MessageTypeCastException}.
     *
     * Note that you can't use instanceof or cast ((TimestampValue) 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.
     */
    TimestampValue asTimestampValue();

    /**
     * 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();
}