Defining Endpoint Properties in the PubSub+ JCSMP API

When a client application using the PubSub+ JCSMP API dynamically creates an endpoint, the properties used to define that endpoint are obtained from the following sources (in the order presented):

  • Endpoint properties and/or provision flags that are passed-in with an endpoint provision API function or method.

    A client can only provide a limited set of endpoint properties and/or provision flags (as listed in Client-Configurable Endpoint Properties) when dynamically creating a durable endpoint (see Provisioning Durable Endpoints Using the PubSub+ JCSMP API).

  • Properties used for CLI-provisioned endpoints.

    Client-created endpoints will be given the same endpoint properties as CLI‑provisioned endpoints; excepting any endpoint properties and/or provision flags passed-in by the client—as noted above—which take precedence. These CLI-provisioned endpoint properties can be taken from an endpoint that an administrator has specifically provisioned and, through two mechanisms:

    • Queues and Topic Endpoints have a name-filter that allows them to match an endpoint name to an endpoint template. This allows client created queues or topic endpoints the ability to dynamically copy attributes from the specified endpoint template. Refer to Setting Name Filters to Match Queue Names or Setting Name Filters to Match Topic Endpoint Names for more information. This feature applies only to the PubSub+ event broker 9.4.0 release and higher.
    • Client Profiles have an optional copy-from-template-on-create command that can be used to copy custom values from an endpoint template to a client created endpoint. However, if no customized endpoint template to be copied is explicitly set, the system defaults for CLI‑provisioned endpoints are used. For more information on this topic, go to Configuring Initial Values for Client-Created Endpoints.
      For event brokers before the 9.4.0 release, you can use the copy-from-on-create command to specify a CLI‑provisioned queue or topic endpoint with custom values, and those values will be applied to any new client‑created endpoints.

Client-Configurable Endpoint Properties

When creating durable queues or topic endpoints, a client application can configure the following endpoint parameters through endpoint properties and/or provision flags that are passed-in with an endpoint provision API function or method:

  • Access Type (exclusive or non-exclusive)—Determines the behavior when multiple Guaranteed Message Flows are bound to a Queue endpoint. (Only Queues can have multiple Flows bound.)
    • Exclusive—Multiple consumer Flows can be bound to the queue (up to 1,000), but only one Flow out of all the bound Flows is able to receive messages at a time (that is, only one Flow can be active). The first Flow to bind to the queue can consume messages from it, and when that Flow disconnects, the next oldest Flow to bind becomes active and can begin receiving messages, and so on.
    • Non-exclusive—All bound consumer Flows are able to receive messages, and when multiple Flows are bound to a non‑exclusive Queue, they receive messages in a round-robin fashion.
  • Maximum Message Size—The maximum size (in bytes) for any one message stored in the endpoint. If a message’s size exceeds this value, the message is not queued to the endpoint.
  • Message Discard Behavior—Specifies how a durable endpoint should handle ingress messages discards that occur due to any of the following conditions. (This property does not affect how an endpoint handles message discards for reasons other than those listed below.)
    • the published message causes the configured message quota for the endpoint to be exceeded
    • the published message exceeds the maximum message size allowed for the endpoint
    • the client published to a topic it has also subscribed to and has an active flow with “No Local Delivery”
    • (for queues only) the message is published directly to a queue, but the queue is shutdown

    By default, the Message Discard Behavior property is enabled for queues and is not enabled for topic endpoints.

    If the Message Discard Behavior property is enabled for an endpoint, failure to spool a message because of one or more of the conditions above results in that message being discarded, and a negative acknowledgment (that is a “nack”) is returned to the sender. In this case, the message cannot be spooled to any other queue or topic endpoint (regardless of whether those endpoints have the Message Discard Behavior property enabled or disabled).

    A nack is only sent to the client if the message was originally published with a Non-Persistent or Persistent delivery mode. If the message was published with a Direct delivery mode, but was changed to Non-Persistent because of a Topic match, and was then discarded, a nack is not returned to the sender. The publishing application is responsible for deciding how to handle the nack—not the messaging API. Solace messaging APIs do not retransmit nacked messages.

    If the Message Discard Behavior property is not enabled for an endpoint, and it encounters one or more of the above conditions, the endpoint discards the ingress message ‘silently’ (that is, it discards the message but returns an acknowledgment to the sender). In this case, the message can be spooled by other endpoints—f they do not encounter any of the conditions listed above.

    The Message Discard Behavior property also affects the behavior of transacted sessions. If acks are being returned to the sender, then the transacted session commit succeeds. If a nack is returned to the sender, then the commit fails. For the enterprise messaging APIs, see Using Local Transactions in the PubSub+ JCSMP API.

  • Maximum Message Redelivery—Specifies the maximum number of times a queue can attempt to redeliver a message to a client. If the number of redelivery attempts for a given message exceeds the Maximum Message Redelivery value, the message is either discarded, or, if a Dead Message Queue (DMQ) has been provisioned on the event broker, the message is removed and placed in the DMQ. (For information on DMQs and making messages eligible for DMQs, see Dead Message Queue Eligibility.)

    The valid range is 0 through 255. 0 mean retry forever and is the default value.

  • Permissions—The permission level on the endpoint for clients other than the owner (that is, the client or administrator that provisioned the endpoint). The owner always has the highest permission level. The following permission levels, from greatest to least, can be assigned.
    • Delete—A client has the permissions of Modify-Topic with the ability to delete the endpoint.
    • Modify-Topic—A client has the permissions of Consume and the ability to change a Topic subscription that attracts messages to the topic endpoint.
    • Consume—A client may read and consume messages from the endpoint. When a client consumes a message, it is acknowledged, which subsequently removes the message from the endpoint.
    • Read-Only—A client may read messages from the endpoint but not consume them.
    • None—No client other than the owner may access the endpoint.
  • Quota—The maximum amount of message spool disk space (in megabytes) permitted for the endpoint. If this quota is exceeded, message cannot be queued to the endpoint. This provides load‑balancing; however, messages can be delivered to consuming clients out of order.
  • Respect Message TTL—Specifies whether the endpoint recognizes Time-to-Live (TTL) eligibility flags set on published messages. If message TTLs are recognized, expired messages can automatically be removed from the endpoint. For information on setting TTL eligibility when publishing messages see Time-To-Live.