跳到主要内容

浏览保证消息

PubSub+ 消息 API 可以使用队列浏览器实例或浏览器流来查看队列上存储的保证消息,顺序是从最旧到最新。

  • PubSub+ C 和 Java RTO API 可以通过浏览器流浏览保证消息。
  • PubSub+ JavaScript、Node.js 和 .NET API 可以通过浏览器对象浏览保证消息。

浏览器流和浏览器对象使您的应用程序能够浏览队列上的消息,并根据需要选择性地移除消息。这可以独立于绑定到队列的任何其他流完成。即使其他应用程序已连接并正在队列上活动,浏览器也允许您连接到独占队列。当您连接到非独占队列时,您可以查看队列上的所有消息。在这种情况下,您的浏览器不受用于向普通消费者投递消息的轮询方法的限制。浏览消息后,客户端仍然可以通过流接收这些消息。

队列的访问类型(独占或非独占)不影响客户端浏览其存储消息的能力,只影响客户端消费这些消息的能力。有关访问类型的更多信息,请参阅定义端点属性。

有关如何浏览队列上消息的示例,请参考:

  • C API 参考文档中的 simpleBrowserFlow.c 示例。

创建浏览器

当使用 JavaScript、Node.js 或 .NET API 浏览队列上存储的保证消息时,客户端必须在会话中创建一个浏览器。

要创建浏览器,请调用以下列出的方法之一,并传入一组浏览器属性。

PubSub+ 消息 API调用方法
.NETISession.CreateBrowser(Endpoint endpointToBrowse, BrowserProperties browserProperties)
JavaScript, Node.js`session.createQueueBrowser(solace.QueueBrowserProperties

如何创建浏览器

在定义新的浏览器属性集时,请确保执行以下操作:

  • 指定您想要浏览的队列端点。只有队列可以被浏览——主题端点不能被浏览。对于 .NET,IEndpoint 是单独传入的。

  • (可选)对于 .NET,指定 Selector 属性的选择器字符串,以仅浏览匹配该选择器的消息。当使用选择器时,等待超时时间可能会显著增加,因为消息总线评估存储消息是否符合选择器需要更长时间。选择器的复杂性也会增加评估时间。(有关选择器及其语法的更多信息,请参阅使用选择器。)

  • (可选)为了提高浏览性能,通过窗口大小(.NET API)属性指定浏览器可以从队列预取并本地缓冲的最大消息数量。

  • (可选)通过 WaitTimeout 属性指定在从 GetNext 操作返回时,如果没有消息可用,则等待的最大超时时间(以毫秒为单位)。

  • 如果会话尚未连接:

    • JavaScript/Node.js — API 将抛出错误。
    • C、C#、Java RTO — 操作取决于 FLOW_BIND_BLOCKING 属性。如果启用此属性(默认设置),API 将阻塞,直到会话连接完成;否则,函数调用将立即返回,并等待会话连接操作完成。
  • 浏览器或浏览器流的生命周期与其创建的会话相关联。因此,关闭会话将关闭该会话中创建的所有浏览器。

创建浏览器流

当使用 C 或 Java RTO API 浏览队列上存储的保证消息时,客户端必须在会话中创建一个浏览器流。

要创建浏览器流,请使用以下列出的方法之一,并传入适当的流属性:

PubSub+ 消息 API调用方法
Java RTOCreateFlowForHandle(...)
CsolClient_session_createFlow(...)

如何创建浏览器流

在定义用于浏览器流的流属性集时,请确保执行以下操作:

  • 指定您想要浏览的队列。只有队列可以被浏览——主题端点不能被浏览。对于 Java RTO API,队列在创建流时指定。对于 C API,队列通过流属性设置。
  • 启用 FlowHandle.PROPERTIES.BROWSER(对于 Java RTO API)或 SOLCLIENT_FLOW_PROP_BROWSER(对于 C API)属性,将流配置为浏览器流,而不是标准的保证消息流。有关创建标准流的更多信息,请参阅创建流。
  • 传入一个指向结构体的指针,该结构体提供此浏览器流上接收的消息和事件的回调函数信息。
  • (可选)指定 Selector 属性的选择器字符串,以仅浏览匹配该选择器的消息。当使用选择器时,等待超时时间可能会显著增加,因为消息总线评估存储消息是否符合选择器需要更长时间。选择器的复杂性也会增加评估时间。有关选择器及其语法的更多信息,请参阅使用选择器。
  • (可选)为了提高浏览性能,通过窗口大小属性指定浏览器可以从队列预取并本地缓冲的最大消息数量。

流的生命周期与其创建的会话相关联。因此,关闭会话将关闭该会话中创建的所有浏览器流。当会话重新连接时,浏览器流将重新绑定到其会话。

关闭浏览器或浏览器流

为了释放分配的内存,当应用程序完成使用时,关闭浏览器实例非常重要。

PubSub+ 消息 API调用方法
Java RTOFlowHandle.destroy()
CsolClient_flow_destroy(...)
.NETIBrowser.Dispose()
JavaScript, Node.jsbrowser.disconnect()

如何关闭浏览器或浏览器流

使用 .NET API 浏览消息

当使用 .NET API 浏览队列上的保证消息时,请执行以下操作:

  1. 获取浏览器实例。
    有关更多信息,请参阅创建浏览器。

  2. (可选) 要检查本地消息缓冲区中是否有立即可用的消息,请调用 HasMore 方法。
    如果本地缓冲区中至少有一条消息,此方法返回 true。如果返回 false,并不一定意味着队列为空,而是本地缓冲区当前不包含任何消息。后续对 HasMoreGetNext 方法的调用可能会分别返回 true 或返回一条消息。

    这些方法提供了对 JMS 实现中使用的 javax.jms.QueueBrowser 枚举模式的支持。

  3. 查看队列中的消息。
    调用 GetNext 方法。

    • GetNext 是一个同步操作,返回消息的完整内容(即,包含所有消息头和负载)。每次调用 GetNext 都会返回队列中的下一条消息(按从旧到新的顺序)。
    • GetNext 方法会检查本地缓冲区中的消息。如果消息可用,它将立即返回;如果没有消息可用,调用将返回 null(当使用 GetNextNoWait() 方法时),或者等待消息,直到达到设置的时间(当使用 GetNext() 方法时)。

客户端应用程序不应假设 API 在浏览存储消息时使用的轮询策略。例如,在浏览消息时,API 可能会从事件代理请求更多消息,或者返回已经缓冲的消息。

使用Java RTO或C API浏览消息

当使用 Java RTO 或 C API 浏览队列上的保证消息时,请执行以下操作:

  1. 创建浏览器流。
    有关更多信息,请参阅创建浏览器流。

    消息将根据引用的回调进行处理。

  2. 当窗口大小设置的最大消息数量达到时,调用 FlowHandle.start()(对于 Java RTO API)或 solClient_flow_start()(对于 C API)以重置窗口,以便可以浏览更多保证消息。

使用JavaScript或Node.js API浏览消息

当使用 JavaScript 或 Node.js API 浏览队列上的保证消息时,请执行以下操作:

  1. 创建一个对象字面量以设置队列浏览器属性。
    唯一必需的属性是 queueDescriptor,即要浏览的队列名称,但您还可以设置以下属性:

    • connectAttempts — 获取和设置在创建与 Solace 事件代理的连接时的最大绑定尝试次数。默认值为 3。
    • connectTimeoutInMsecs — 在创建与 Solace 事件代理的连接时的绑定超时时间(以毫秒为单位)。默认值为 10000。
    • transportAcknowledgeThresholdPercentage — 发送确认的阈值,以百分比表示。默认值为 60。
    • transportAcknowledgeTimeoutInMsecs — 保证消息的传输确认超时时间(以毫秒为单位)。默认值为 1000。
    • windowSize — 保证消息投递的窗口大小。默认值为 255。

    有关队列浏览器属性的更多信息,请参阅 JavaScript 参考文档中的 PubSub+ 消息 API 的 solace.QueueBrowserProperties

    下面的示例显示了一个仅包含队列名称 的简单队列浏览器属性对象:

    const queueBrowserProps = {
    queueDescriptor: { name: "queueName", type: solace.QueueType.QUEUE },
    };
  2. 使用 createQueueBrowser() 函数创建浏览器对象,并使用 connect() 函数将其连接到事件代理。

    queuebrowser = session.createQueueBrowser(queueBrowserProps);
    queuebrowser.connect();
  3. (可选) 如果您需要因任何原因暂停队列浏览器,请使用 stop() 函数。要重新启动浏览器,请使用 start() 函数。

    queuebrowser.stop();
    // 执行任何操作,例如等待 1 秒以允许消息处理赶上:setTimeout(() => {}, 1000);
    queuebrowser.start();
  4. 队列浏览器是一个事件发射器,您可以使用事件监听器选择应用程序订阅的事件:

    • solace.QueueBrowserEventName.UP — 队列浏览器已连接。
    • solace.QueueBrowserEventName.DOWN — 队列浏览器已断开连接。
    • solace.QueueBrowserEventName.DOWN_ERROR — 队列浏览器被路由器断开连接,可能是由于操作员干预。
    • solace.QueueBrowserEventName.MESSAGE — 在队列浏览器上接收到一条消息。
    • solace.QueueBrowserEventName.DISPOSED — 队列浏览器已被释放。不会再发出任何事件。
    • solace.QueueBrowserEventName.GM_DISABLED — 队列浏览器不会连接,因为当前会话与保证消息不兼容。
    • solace.QueueBrowserEventName.CONNECT_FAILED_ERROR — 队列浏览器尝试连接但未成功。

    有关队列浏览器事件的更多信息,请参阅 JavaScript 参考文档中的 PubSub+ 消息 API 的 solace.QueueBrowserEventName

    要开始接收浏览的消息,请为 MESSAGE 创建事件监听器。此监听器将继续接收浏览的消息,直到浏览器停止、断开连接或已接收队列中的所有消息。以下示例显示了浏览消息的事件监听器:

    queuebrowser.on(solace.QueueBrowserEventName.MESSAGE, (message) => {
    // 浏览的消息:
    receivedMessage = message;
    // 如果您想从队列中移除该消息:
    queuebrowser.removeMessageFromQueue(receivedMessage);
    });

    如果 QueueBrowser 上没有 solace.QueueBrowserEventName.MESSAGE 的监听器,消息将被内部排队,直到添加了监听器。

在浏览时移除消息

客户端可以在浏览队列时选择性地移除存储的保证消息。移除浏览的消息会从队列中删除这些消息,因此它们不能再被消费客户端接收(或者如果它们曾经被投递到消费者,则不再重新投递)。

在浏览时选择性移除消息在以下情况下非常有用:管理员希望从队列中移除“卡住”的保证消息,而无需修改或干扰现有的消费客户端。如果消息满足以下条件之一,则可能会“卡住”:

  • 已被客户端接收,但该客户端未能确认该消息。
  • 所有活动的消息选择器都未能匹配该消息,因此该消息未被投递到任何客户端。

移除消息时不会返回确认。此外,如果尝试移除不存在的消息或已经从队列中移除的消息,也不会返回错误。

要移除浏览的消息,请执行以下操作:

  • 当使用 JavaScript、Node.js 或 .NET API 时,调用以下列出的方法之一,针对该消息。
  • 当使用 Java RTO 或 C API 时,对在浏览器流上接收的消息发送确认。
PubSub+ 消息 API调用方法
Java RTO- FlowHandle.ack(long adMsgId)
  • FlowHandle.ack(MessageHandle rxMsg)
CsolClient_flow_sendAck(solClient_opaqueFlow_pt opaqueFlow_p, solClient_msgId_t msgId)
.NET- IBrowser.Remove(IMessage)
  • IBrowser.Remove(Int64)
JavaScript, Node.jssolace.QueueBrowser.removeMessageFromQueue(message)

如何移除浏览的消息