cn.wjybxx.dson.DsonReader Maven / Gradle / Ivy
/*
* Copyright 2023-2024 wjybxx([email protected])
*
* 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 cn.wjybxx.dson;
import cn.wjybxx.dson.types.*;
import javax.annotation.Nonnull;
/**
* 1.读取数组内普通成员时，name传null，读取嵌套对象时使用无name参数的start方法
* 2.为减少API数量，我们的所有简单值读取都是带有name参数的，在已读取name的情况下，接口的name参数将被忽略。
*
* @author wjybxx
* date - 2023/4/20
*/
@SuppressWarnings("unused")
public interface DsonReader extends AutoCloseable {
@Override
void close();
/**
* 获取当前上下文的类型
*/
DsonContextType getContextType();
/** 当前是否处于应该读取type状态 */
boolean isAtType();
/**
* 读取下一个值的类型
* 如果到达对象末尾，则返回{@link DsonType#END_OF_OBJECT}
*
* 循环的基本写法：
*
{@code
* DsonType dsonType;
* while((dsonType = readDsonType()) != DsonType.END_OF_OBJECT) {
* readName();
* readValue();
* }
* }
*/
DsonType readDsonType();
/**
* 查看下一个值的类型
* 1.该方法对于解码很有帮助，最常见的作用是判断是否写入了header
* 2.不论是否支持mark和reset，定义该方法都是必要的，以允许实现类以最小的代价实现
*/
DsonType peekDsonType();
/** 当前是否处于应该读取name状态 */
boolean isAtName();
/** 读取下一个值的name */
String readName();
/**
* 读取下一个值的name
* 如果下一个name不等于期望的值，则抛出异常
*/
void readName(String name);
/** 当前是否处于应该读取value状态 */
boolean isAtValue();
/**
* 获取当前的数据类型
* 1.该值在调用任意的读方法后将变化
* 2.如果尚未执行过{@link #readDsonType()}则抛出异常
*/
@Nonnull
DsonType getCurrentDsonType();
/**
* 获取当前的字段名字
* 1.该值在调用任意的读方法后将变化
* 2.只有在读取值状态下才可访问
*
* @return 当前字段的name
*/
String getCurrentName();
// region 简单值
int readInt32(String name);
long readInt64(String name);
float readFloat(String name);
double readDouble(String name);
boolean readBool(String name);
String readString(String name);
void readNull(String name);
Binary readBinary(String name);
ObjectPtr readPtr(String name);
ObjectLitePtr readLitePtr(String name);
ExtDateTime readDateTime(String name);
Timestamp readTimestamp(String name);
// endregion
// region 容器
void readStartArray();
void readEndArray();
void readStartObject();
void readEndObject();
/** 开始读取对象头，对象头属于对象的匿名属性 */
void readStartHeader();
void readEndHeader();
/**
* 回退到等待开始状态
* 1.该方法只回退状态，不回退输入
* 2.只有在等待读取下一个值的类型时才可以执行，即等待{@link #readDsonType()}时才可以执行
* 3.通常用于在读取header之后回退，然后让业务对象的codec去解码
*/
void backToWaitStart();
default void readStartArray(String name) {
readName(name);
readStartArray();
}
default void readStartObject(String name) {
readName(name);
readStartObject();
}
// endregion
// region 特殊支持
/**
* 如果当前是数组上下文，则不产生影响；
* 如果当前是Object上下文，且处于读取Name状态则跳过name，否则抛出状态异常
*/
void skipName();
/**
* 如果当前不处于读值状态则抛出状态异常
*/
void skipValue();
/**
* 跳过当前容器对象(Array、Object、Header)的剩余内容
* 调用该方法后，{@link #getCurrentDsonType()}将返回{@link DsonType#END_OF_OBJECT}
* 也就是说，调用该方法后应立即调用 readEnd 相关方法
*/
void skipToEndOfObject();
/**
* {@link DsonType#INT32}
* {@link DsonType#INT64}
* {@link DsonType#FLOAT}
* {@link DsonType#DOUBLE}
*/
Number readNumber(String name);
/**
* 将value的值读取为字节数组
* 1.支持类型：String、Binary、Array、Object、Header；
* 2.返回的bytes中去除了value的length信息；
* 3.只在二进制流下生效。
*
* 该方法主要用于避免中间编解码过程，eg：
*
* A端： B端 C端
* object->bytes bytes->bytes bytes->object
*
*/
byte[] readValueAsBytes(String name);
/**
* 附近一个数据到当前上下文
*
* @return 旧值
*/
Object attach(Object userData);
Object attachment();
/** 读操作指导 */
DsonReaderGuide whatShouldIDo();
}