diff --git a/ContentGrabbingJi-framework-api/src/main/java/net/lamgc/cgj/bot/framework/message/MessageChain.java b/ContentGrabbingJi-framework-api/src/main/java/net/lamgc/cgj/bot/framework/message/MessageChain.java index c46f580..e57b214 100644 --- a/ContentGrabbingJi-framework-api/src/main/java/net/lamgc/cgj/bot/framework/message/MessageChain.java +++ b/ContentGrabbingJi-framework-api/src/main/java/net/lamgc/cgj/bot/framework/message/MessageChain.java @@ -18,6 +18,7 @@ package net.lamgc.cgj.bot.framework.message; import java.util.List; +import java.util.Objects; import java.util.concurrent.CopyOnWriteArrayList; /** @@ -29,22 +30,95 @@ public final class MessageChain implements Message { private final List contents = new CopyOnWriteArrayList<>(); + /** + * 构造一个无内容消息链对象. + */ public MessageChain() {} + /** + * 通过一些字符序列构造一个有内容的消息链对象. + * @param contents 字符序列数组, 用于组成消息链的初始内容. + */ public MessageChain(CharSequence... contents) { plus(contents); } - public void plus(CharSequence... content) { - addMultiContents(content); + /** + * 添加一组字符序列到消息链尾部. + * @param contents 消息内容. + * @throws NullPointerException 当 contents 为 {@code null} 时抛出(元素内含有 {@code null} 不会抛出). + * @throws IllegalArgumentException 当添加消息链对象本身时抛出. + */ + public void plus(CharSequence... contents) { + addMultiContents(contents); } - public void plus(Message... message) { - addMultiContents(message); + /** + * 添加一组 {@link Message} 对象到消息链尾部. + * @param messages 消息对象. + * @throws NullPointerException 当 messages 为 {@code null} 时抛出(元素内含有 {@code null} 不会抛出). + * @throws IllegalArgumentException 当添加消息链对象本身时抛出. + */ + public void plus(Message... messages) { + addMultiContents(messages); } - public void plus(BotCode... botCode) { - addMultiContents(botCode); + /** + * 添加一组 {@link BotCode} 对象到消息链尾部. + * @param botCodes BotCode 对象. + * @throws NullPointerException 当 botCodes 为 {@code null} 时抛出(元素内含有 {@code null} 不会抛出). + * @throws IllegalArgumentException 当添加消息链对象本身时抛出. + */ + public void plus(BotCode... botCodes) { + addMultiContents(botCodes); + } + + /** + * 插入一个字符序列对象到消息链的指定位置中. + * @param index 插入位置的索引, 该索引为插入元素所在索引. + *

比如说 {@code ['a', 'b', 'c']} 插入 [index=2, content='d'], + * 则插入后为 ['a', 'b', 'd', 'c'], 原本处于 index(2) 的元素会往后移动. + * @param content 欲插入的消息元素. + */ + public void insert(int index, CharSequence content) { + checkMessageEqualThis(Objects.requireNonNull(content)); + contents.add(index, content instanceof Message ? (Message) content : new CharSequenceMessage(content)); + } + + /** + * 删除指定索引的消息元素. + * @param index 欲删除的消息元素所在索引. + * @return 返回被删除的消息元素. + * @throws IndexOutOfBoundsException 当 index 小于 0 或大于消息链长度时抛出. + */ + public Message delete(int index) { + return contents.remove(index); + } + + /** + * 清空消息链中的所有元素. + */ + public void clear() { + contents.clear(); + } + + /** + * 检查消息链是否为空. + *

当消息链内不含任何消息元素时, 消息链为空. + *

该方法等效于 {@code size() == 0} + * @see #size() + * @return 如果消息链不含任何消息元素, 则返回 {@code true}. + */ + public boolean isEmpty() { + return size() == 0; + } + + /** + * 获取消息链大小. + * @return 返回消息链中的消息元素数量. + */ + public int size() { + return contents.size(); } /** @@ -53,7 +127,11 @@ public final class MessageChain implements Message { * @see #addContent(Message) 底层实现. */ private void addMultiContents(CharSequence[] contents) { + Objects.requireNonNull(contents); for (CharSequence content : contents) { + if (content == null || content.length() == 0) { + continue; + } if (content instanceof Message) { addContent((Message) content); } else { @@ -70,10 +148,20 @@ public final class MessageChain implements Message { * @throws IllegalArgumentException 不允许 MessageChain 添加本身. */ private void addContent(Message content) { - if (this.equals(content)) { + checkMessageEqualThis(content); + contents.add(content); + } + + /** + * 检查消息是否为本身. + *

如果消息为本身, 则抛出异常. + * @param content 内容对象. + * @throws IllegalArgumentException 当 content 为 MessageChain 本身时抛出. + */ + private void checkMessageEqualThis(CharSequence content) { + if (content == this) { throw new IllegalArgumentException("Adding the MessageChain itself is not allowed"); } - contents.add(content); } @Override