Mục lục bài viết

Legacy SEMP

This section provides information on the older version of SEMP, which uses an XML schema for monitoring and managing event brokers. For information on the current SEMP release, SEMP v2, which is a RESTful API, see SEMP. You should be aware that configuring the same event broker object concurrently with both SEMP v2 and Legacy SEMP/CLI is not supported, and may result in unexpected behavior.

Using SEMP to Manage and Monitor Event Brokers

Solace Element Management Protocol (SEMP) is a request/reply protocol that uses an XML schema to identify all managed objects available in an event broker. Any object available through the event broker Command Line Interface (CLI) or SolAdmin is also available through SEMP.

Applications can use SEMP to manage and monitor an event broker. It uses a simple request/reply paradigm to send XML-encoded requests to the event broker and receive corresponding XML-encoded replies. These requests and replies parallel the commands and replies offered through CLI.

SEMP XML-encoded commands and replies are either wrapped in HTTP requests and responses and sent over a TCP connection (SEMP Request over HTTP) to the management interface, or sent over the event broker message bus (SEMP Request Over Message Bus) using one of the Solace messaging APIs.

The following figure shows both the SEMP Request over HTTP and SEMP Request Over Message Bus access methods.

SEMP Access Mechanisms

Each time a user successfully logs in or out, or fails to authenticate for a SEMP session, the event broker writes an authentication event to the event log. Therefore, a persistent SEMP connection should be used when possible to avoid a high volume of authentication event logs.

SEMP Request and Reply Schema Files

You can obtain the SEMP Request or Reply schema file from an event broker by performing a GET on one of the following URIs:

To obtain the SEMP Request schema file, perform a GET on the following URI:

http://<HOST>/SEMP/v1/requestSchema.xsd
To obtain the SEMP Reply schema file, perform a GET on the following URI:

http://<HOST>/SEMP/v1/replySchema.xsd

SEMP Polling Frequency Guidelines

The event broker supports a maximum SEMP polling rate of ten requests per second.

When you are using SEMP paging and a more-cookie is returned, the single page constitute a single request. (For information on oversized responses and the more-cookie, refer to SEMP Paging.)

The following SEMP requests should not be polled more than once every 30 seconds due to the large amount of data that could be returned.

show cache-instance <name> remote status
show cache-instance <name> remote topics
show queue <name> message-vpn <name> rates
show smrp subscriptions
show topic-endpoint <name> message-vpn <name> rates
The time the responses take to be returned may vary depending on the amount of information on the event broker. For large amounts of data, the poll responses may take more than 30 seconds.

The following SEMP requests should not be polled.

show queue <name> message-vpn <name> messages
show topic-endpoint <name> message-vpn <name> messages

Secure Connections

Applications can optionally create secure connections to an event broker to safeguard authentication information and the data that is transmitted. By default, the SEMP data that is exchanged between a management application and an event broker through an established connection is transmitted as plain text. Secure connections use Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) protocols to encrypt the SEMP data that is exchanged so that SEMP data is transported using TLS/SSL over TCP instead of plain text over TCP.

The Solace PubSub+ supports TLSv1.0, TLSv1.1, and TLSv1.2 (SSLv1.0, v2.0, and v3.0 are not supported).

To create a TLS/SSL-encrypted connection, the event broker must be properly configured for TLS/ SSL service and the appropriate server certificate must be in place. For information on configuring an event broker to allow for secure connections, refer to TLS/SSL Service.

The following configurations are also required on the client-side:

When using SEMP over HTTP, an HTTPs URI scheme and a secure port (port 443, by default) must be specified to create a secure connection.
When using SEMP over message bus service, a number of TLS/SSL-specific Session properties must be specified to create a secure Session.
For information on these properties, refer to Creating Secure Sessions for the Solace enterprise APIs and/or Secure Connections for the Solace JMS API.

SEMP Request Over HTTP Service

A management application can use the SEMP interface to communicate with the event broker over HTTP as follows:

A management application opens a TCP connection to port 80 on a Solace PubSub+ appliance (port 8080 on a software event broker).
If a TLS/SSL connection is required, a secure port on the event broker (by default, port 443) must be used. For information on how to set the SSL listen port on an event broker, refer to Enabling System-Level SEMP Service.
The management application then sends HTTP POST messages to issue SEMP commands to the event broker.
If a TLS/SSL connection is required, an HTTPs URL scheme must be used.

The management application must wait for the reply to each command before issuing the next command.
The event broker sends an HTTP response back for each HTTP POST request, containing the SEMP reply.
At this point, the management application can close the connection, or keep the connection open for future HTTP POST requests.

The event broker supports a maximum of 500 concurrent SEMP requests over HTTP sessions.

SEMP Request Over Message Bus Service

The SEMP Request Over Message Bus feature is provided as a light-weight alternative to the full administrative access that is supported by the SEMP Request Over HTTP transport service. This feature allows network management and client applications that support request/reply convenience functions and methods to manage an event broker. For example, a client application using a Solace messaging API can publish a request to a destination that uses a specific command topic, and the event broker returns a reply back to the client application.

MQTT and OpenMAMA clients do not support SEMP Request Over Message Bus functionality.

The SEMP Request Over Message Bus, when enabled for a Message VPN, can give a client application access to show User EXEC commands, client Admin EXEC commands, and distributed cache Admin EXEC commands within the Message VPN that the client application is connected to. Unless a Message VPN has been designated as the Management Message VPN, an application may only request data through show commands and run administration commands for the Message VPN to which it is connected. The event broker will reject any requests for information about any managed object not contained in that Message VPN.

By default, the SEMP data that is sent between a client application and an event broker through a connected Session is transmitted as plain text. However, it is also possible to establish a secure Session that uses TLS/SSL protocols to encrypt the SEMP data. For information on specific TLS/SSL Session properties and how to establish a secure Session, refer to Creating Secure Sessions for the Solace enterprise APIs and/or Important Connection Properties for the Solace JMS API.

SEMP on software event brokers does not support TLSv1.0.

SEMP Formatting

To use the SEMP Request transport service, the following formatting conventions are used:

HTTP Request Format

The following is an example of an HTTP POST request from a management application to issue a SEMP command to an event broker:

POST /SEMP HTTP/1.1

Authorization: Basic <usernameAndPassword>

Content-Length:<length>

Where:

<usernameAndPassword> is the username and password for the user. The username and password must be encoded as described in RFC 2617: Section 2: Basic Authentication Scheme.

OAuth authentication is also supported using one or more OAuth tokens in the HTTP Authorization header as a bearer token. For more information see OAuth Authentication.

<length> indicates the length (in bytes) of the SEMP command that follows the HTTP header.

<SEMP command> is the contents of the SEMP command being sent (see SEMP Command Format). The application can only send one SEMP command for each HTTP POST request.

HTTP Response Format

The following is an example of an event broker HTTP response to a management application’s SEMP command:

HTTP/1.1 200 OK

Content-Length: <length>

Where:

<length> indicates the length (in bytes) of the SEMP reply that follows the HTTP header

<SEMP reply> is the contents of the SEMP reply that is returned by the event broker (see SEMP Reply Format)

An HTTP response of “200 OK” is returned if the command was accepted by the event broker (even if it was not successfully executed). If there is an authentication failure, the following response is returned:

01 Unauthorized

Basic Realm=”CLI”

Otherwise, a response of “400 ERROR” is returned.

SEMP Schema Version

SEMP uses an XML schema to identify all managed objects available in an event broker.

The SEMP command contains an optional SEMP schema version string that specifies which SEMP schema is to be used in the validation of the command by the event broker.

When received by an event broker in a command, the SEMP schema version string is processed in the following manner,

If a version string is provided,

and matches a SEMP schema installed on the event broker, then the command is validated with the specified schema.
and does not match any installed SEMP schema, then the command is validated with the latest installed schema.

If a version string is not provided, the event broker validates the command using the latest installed schema.

As of Solace PubSub+ software event broker version 8.7+ and Solace PubSub+ appliance version 8.3+, it is recommended to not include a SEMP version string in commands, and only include one if a known deprecated behavior is needed from a particular SEMP schema.

SEMP Command Format

For both SEMP Request over HTTP and SEMP Request Over Message Bus access methods, the format of SEMP commands within a request is modeled after the Solace CLI. Each SEMP command is the equivalent of a single CLI command.

SEMP commands are formatted in XML, following the schema in the semp-rpc-soltr.xsd file provided with the Solace PubSub+ software release bundle. White space (including line-end characters) is optional in the SEMP command. The top‑level element is <rpc>, and the next-level element corresponds to the command being issued. Inside the <rpc> element are the keywords and parameters of the command.

Example:

<rpc>

<show>

</client>

</show>

SEMP does not provide a concept of command modes. All commands are issued at the top level of the command mode hierarchy. In particular, the enable and configure commands are not required or supported in SEMP.

If a known deprecated behavior is needed from a particular SEMP schema, a SEMP version string is specified inside the <rpc> element. For example, to specify schema version 7.1, use <rpc semp-version='soltr/7_1'>.

SEMP Reply Format

For both SEMP Request over HTTP and SEMP Request Over Message Bus access methods, the SEMP interface replies indicate the success or failure of a SEMP command, in addition to the reason code for any failure. SEMP replies are formatted in XML, following the schema in the semp-rpc-reply-soltr.xsd file.

The following is an example of a successful reply to the command described in SEMP Command Format (White space, including line-end characters, is optional in a SEMP reply):

<rpc-reply semp-version=”soltr/8_3_0″>

<rpc>

<show>

<primary-virtual-router>

<client-address>192.168.1.180:58305</client-address>

<profile>default</profile>

<num-subscriptions>1</num-subscriptions>

<message-vpn>default</message-vpn>

</client>

</primary-virtual-router>

<internal-virtual-router>

<client-address>127.55.55.55:56244</client-address>

<name>#client</name>

<profile>#client-profile</profile>

<num-subscriptions>2</num-subscriptions>

<message-vpn>default</message-vpn>

<description>Internal Message Bus</description>

</client>

</internal-virtual-router>

</client>

</show>

</rpc>

<execute-result code=”ok”/>

</rpc-reply>

As shown in the example above, a successfully parsed SEMP command always generates <rpc-reply> and <execute-result>element tags. Additionally, in the case of SEMP show commands, a number of element tags detailing the command name (without parameters) and output are also generated.

The execute-result code has either a value of “ok”, or “fail”. For a failure, the reason (represented by a string) and reason code (represented by an integer) are also provided.

Publishing an HTTP SEMP Request with cURL

The following simple example shows a simple HTTP SEMP request published to the event broker with cURL (http://curl.haxx.se/).

Using the Solace CLI, you can view global event broker stats with the show stats client User EXEC command. The following snippet shows the XML for the equivalent SEMP request:

<rpc>

<show>

<stats>

</stats>

</show>

</rpc>

If this XML code is put in a file called request.xml, you can use cURL to send it to the HTTP listen port of the event broker management interface.

Solace PubSub+ appliance example:

curl -d @request.xml -u admin:admin http://192.168.128.12:80/SEMP

Solace PubSub+ software event broker example:

curl -d @request.xml -u admin:admin http://192.168.128.12:8080/SEMP

The response provides the same client statistics that would be provided through the CLI output, but these statistics that the SEMP provides are provided formatted in XML (refer to SEMP Reply Format).

Configuring SEMP Over Message Bus Services

The SEMP Request Over Message Bus service is configured on a per Message VPN basis.

To configure SEMP Request Over Message Bus service on a Message VPN through the CLI, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>

solace(configure/message-vpn)# semp-over-msgbus

solace(configure/message-vpn/semp-msgbus)#

The CLI is now in the configuration mode for the SEMP Request Over Message Bus service on the specified Message VPN.

The example below shows the hierarchical structure of the SEMP Request Over Message Bus service command tree. This shows how you can enable or disable all client access to SEMP Request Over Message Bus service for the Message VPN or limit client access to specific Admin and Show commands for the SEMP Request Over Message Bus service.

SEMP Over Message Bus Service Command Hierarchy

SEMP over Message Bus: Enabled/Disabled

Admin commands: Enabled/Disabled

Client commands: Enabled/Disabled

Distributed Cache commands: Enabled/Disabled

Show commands: Enabled/Disabled

Legacy Show Clear commands: Enabled/Disabled

To enable or disable client access to SEMP Request Over Message Bus service for the Message VPN, refer to Allowing SEMP Over Message Bus Service.

When SEMP Request Over Message Bus service is enabled, you can further control client access to the following commands for the SEMP Request Over Message Bus service:

By default, SEMP Request Over Message Bus service is enabled for a Message VPN, but access to each group of admin and show commands is disabled.

Enabling SEMP Service for Management VPNs

To allow system-wide access to SEMP service over Message Bus, you can enable SEMP service for the Message VPN that is designated as the Management Message VPN (refer to Designating Management Message VPNs).

A single Message VPN can be designated as the Management Message VPN for an event broker. SEMP requests published by a client application connected to the Management Message VPN may request system-level information, as well as information for any of the Message VPNs configured on the event broker. Clients connected to the Management Message VPN have permission to clear events (at client or Distributed Cache level) and delete messages in Distributed Caches across all Message VPNs.

Allowing SEMP Over Message Bus Service

To allow clients to run SEMP commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# no shutdown

By default, SEMP Request Over Message Bus service is enabled for a Message VPN.

To not allow clients to run SEMP commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# shutdown

Allowing Access to Admin Commands

The Admin EXEC commands contain the Client EXEC Admin commands and the Distributed Cache Admin EXEC commands. To stop clients from running Admin EXEC commands over the message bus denies them access to both the Client EXEC Admin commands and the Distributed Cache Admin EXEC commands.

To allow clients to run Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# no admin-cmds shutdown
To stop clients from running Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# admin-cmds shutdown

By default, Admin EXEC SEMP Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Client Admin Commands

The Client EXEC Admin commands can be used to clear events.

To allow clients to run Client Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# no admin-cmds client-cmds shutdown
To stop clients from running Client Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# admin-cmds client-cmds shutdown

By default, Client Admin EXEC SEMP Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Distributed Cache Admin Commands

The Distributed Cache Admin EXEC commands can be used to clear Distributed Cache events and delete messages from the given Distributed Cache.

To allow clients to run Distributed Cache Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# no admin-cmds distributed-cache-cmds shutdown
To stop clients from running Distributed Cache Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# admin-cmds distributed-cache-cmds shutdown

By default, Distributed Cache Admin EXEC SEMP Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Show Commands

The show User EXEC commands include show commands for data and statistics scoped within the Message VPN that the client is connected to.

To allow clients to run show User EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# no show-cmds shutdown
To stop clients from running show User EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# show-cmds shutdown

By default, show User EXEC Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Legacy Show Clear Commands

By default, legacy SEMP access (that is, SEMP show and administration requests published to topic “#P2P/[router name]/#client/SEMP”) is enabled on each Message VPN for backwards compatibility. However, as of software version 5.4, legacy SEMP access is deprecated, and it is recommended that you publish SEMP show and administration requests published to the current topic “#SEMP/<router name>/<cmd-topic>” (refer to Publishing SEMP Requests Over the Message Bus) and avoid enabling legacy SEMP access.

To allow clients to run legacy SEMP commands on the event broker SEMP Request Over Message Bus service for the given Message VPN, enter the following CONFIG command:
solace(configure/message-vpn/semp-msgbus)# no legacy-show-clear-cmds shutdown
To stop clients from running legacy SEMP commands on the event broker SEMP Request Over Message Bus service for the given Message VPN, enter the following VPN CONFIG command:
solace(configure/message-vpn/semp-msgbus)# legacy-show-clear-cmds shutdown

SEMP Paging

When retrieving multiple objects (i.e. Queues, Message VPNs or Subscriptions) via SEMP, you must use SEMP paging (also called “sequenced get”), and the number of objects you request must never exceed 100. When using the SEMP Request Over Message Bus service, you must further limit your object count to ensure your response fits within the maximum response size of 89,000 bytes, and when using SEMP over HTTP, your response must fit within the maximum response size of 33,554,432 bytes.

SEMP show commands that require paging support “sequenced get” and provide a “more-cookie” to receive the full response through multiple smaller responses.

If a SEMP request would result in an oversized response, the event broker responds with “response too big: use sequenced get”. When this occurs, refer to the SEMP schema file to create your send request with the “sequenced get” parameters. The sequenced get parameters consist of the “count” and “num-elements” XML attributes.

When using a “sequenced get”, the event broker could include a “more-cookie” in the response. This more-cookie can be retrieved from the SEMP response with the following XML XPath: “//more-cookie”. The more-cookie can be sent back to the event broker in another SEMP request to receive the next portion of the response. This is repeated to retrieve all portions of the response from the event broker. The responses from “sequenced get” and “more-cookie” can be used individually or reassembled into a single SEMP response. Both the “more-cookie”, individual SEMP responses, and the entire response (when reassembled) adhere to the SEMP response schema.

In release 9.7.0 and later, wildcarded show commands may return paged data even if paging was not requested, especially if the command takes more than a few seconds to execute. In addition, when paged data is returned, the number of entries returned may be fewer than the number of entries requested. In some cases, paged responses may be completely empty (including only a more-cookie). Clients must be written to accept paged data of any size less than or equal to the requested page size.

If this behaviour prevents your client from functioning, you can use the configure service semp legacy-timeout command to assist in keeping your system running while you update your clients to use paging. When enabled, it increases the amount of time available for the system to produce a response before paging is forced on a client. Note that this is only intended to be used to keep a system running for a short period of time while clients are updated to use paging.

When using show commands with a sort parameter (for example, show client * sorted-stats total-client-messages-sent),using a “sequenced get” will return the top elements (up to the specified number of elements), and a “more-cookie” will not be present (although more elements may be present).

Available SEMP Over Message Bus Commands

The following commands can be executed over the message bus:

Show User EXEC commands—These commands enable applications to display configuration and statistical information only for the Message VPN that the client is connected to. For example, the show client * command will display client configuration and status information only for those clients within the Message VPN that the client application is connected to.
A client application cannot display information for a Message VPN that it is not connected to, and it cannot display system-level information.

The only exception to this limitation is if the client application is connected to the event broker’s Management Message VPN. In this case, it can successfully run all show commands (whether they concern System-level information or Message VPN-scoped information).

If a client executes system-level show commands, such as show hardware or show version, and it is not connected to the Management Message VPN, a permission error “invalid request: not authorized to run this command” is returned.

To view all of the possible show commands, enter the following User EXEC command:

solace> show ?
Client Admin EXEC commands—These commands enable applications to clear and reset the given client’s event notification for a specified one-shot event. The following client admin EXEC command can be executed over the message bus:
- admin client <name> message-vpn <vpn-name> [primary][backup] [static] clear-event <event-name>
Distributed Cache Admin EXEC commands—These commands enable applications to clear event notifications for the given Distributed Cache or delete messages from the given Distributed Cache. These commands also enable applications to start a single PubSub+ Cache Instance or all PubSub+ Cache Instances in a Cache Cluster that do not have Auto Start Mode enabled. The following distributed cache admin EXEC commands can be executed over the message bus:
- admin distributed-cache <name> message-vpn <vpn-name> clear-event <event-name> [cache-cluster <cluster-name>] [cache-instance <instance-name>]
- admin distributed-cache <name> message-vpn <vpn-name> delete-messages <topic> [cache-cluster <cluster-name>] [cache-instance <instance-name>]

For more information on the CLI equivalent of these commands and details for the parameters, refer to Performing PubSub+ Cache Administrative Tasks.

Publishing SEMP Requests Over the Message Bus

Client applications can use the Java, C, and .NET messaging APIs to make SEMP requests over the message bus. Client applications must publish any SEMP requests over the message bus to the following topic destination:

#SEMP/<router name>/<cmd-topic>

Where:

router name is the hostname of the event broker to send the request to.

cmd-topic is a command specific topic destination to publish the SEMP request to. The following command topics can be used:

#SEMP/<router name>/SHOW—The command topic destination for show User EXEC commands, which display Message VPN-scoped information such as configuration data, statistics, and client information.
For more information on the CLI equivalent of this command, refer to Monitoring VPN Configurations and Stats.
#SEMP/<router name>/ADMIN/CLIENT—The command topic destination for Client Admin EXEC commands, which enable applications to clear and reset the given client’s event notification for a specified one-shot event.
#SEMP/<router name>/ADMIN/DISTRIBUTED-CACHE—The command topic destination for Distributed Cache Admin EXEC commands, which enable applications to clear event notifications for the given Distributed Cache or delete messages from the given Distributed Cache.

The following are examples of full command topics that SEMP requests could be published to:

#SEMP/SolaceNewYork/SHOW

#SEMP/SolaceLondon2/ADMIN/CLIENT

#SEMP/SolaceNewJersey/ADMIN/DISTRIBUTED-CACHE

When developing a client application that can publish a SEMP request and handle its response, each SEMP request and each SEMP response must fit within a single message. Multi-part messages are not supported.

The event broker allows one Message VPN to be designated as the Management Message VPN. Clients connected to this Management Message VPN may then request both system-level information as well as information pertaining to any of the Message VPNs configured on the event broker. Likewise, clients connected to the Management Message VPN may run administration commands for any Message VPN configured on the event broker. For more information, refer to Designating Management Message VPNs.

Related Samples

For a complete example of how to publish SEMP requests over the message bus, a sample file is provided for the JCSMP, C, and .NET APIs. There is a readme file at the top of the example directory that describes how to build and run the example code.

API
Path to SEMP Sample File

JCSMP

samples/src/com/solacesystems/jcsmp/samples/introsamples/SempGetOverMB.java

samples/src/com/solacesystems/jcsmp/samples/introsamples/SempHttpSetRequest.java

samples/src/com/solacesystems/jcsmp/samples/introsamples/SempPagingRequests.java

C
ex/sempGetOverMb.c
CCSMP (.NET)

ex/SolClientSamples/SempGetOverMB.cs

ex/SolClientSamples/SempHttpSetRequest.cs

ex/SolClientSamples/SempPagingRequests.cs

Publishing SEMP Requests with the JCSMP

To publish a SEMP request with the JCSMP, perform the following steps:

Create a Session and Producer.
Create a message topic to publish the SEMP request to:
Topic topic = JCSMPFactory.onlyInstance().createTopic(String topicString);

The topic must be constructed as follows: “#SEMP/<router name>/<cmd-topic>“
Create a request message:
BytesXMLMessage requestMsg = _producer.createBytesXMLMessage();
Set the SEMP request string as the binary attachment:
requestMsg.writeAttachment(byte[] byteInputBuffer);
Create a requestor on the session, and send the request.
The SEMP response is returned as a BytesXMLMessage:

Requestor requestor = _session.createRequestor();
BytesXMLMessage replyMsg = requestor.request(
requestMsg,
long timeoutMillis,
topic
);
Obtain the binary attachment data from the reply message. The binary attachment contains the SEMP reply for the command topic in the publish request.
replyMsg.readAttachmentBytes(byte[] bytes);

For API specifications and more details, refer to the Products.

Publishing SEMP Requests with the C API

To publish a SEMP request with the C API, perform the following steps:

Create a Session.
Allocate a message for requests.
if ( ( rc = solClient_msg_alloc ( &msg_p ) ) != SOLCLIENT_OK ) {

        common_handleError ( rc, “solClient_msg_alloc()” );

        return;

    }
Create a SEMP request message and specify the topic destination to publish the SEMP request to. The topic destination must be constructed as follows:
solClient_destination_t topic

topic.dest = topicString;

topic.destType = SOLCLIENT_TOPIC_DESTINATION;
Create a request message and set its Destination to the topic created in Step 3:
solClient_msg_setDestination ( msg_p, &topic );

Set the SEMP request string as the binary attachment:

solClient_msg_setBinaryAttachmentPtr

( msg_p, byteInputBuffer, strlen( byteInputBuffer ));
Call the solClient_session_sendRequest method:
solClient_opaqueMsg_pt replyMsg_p;

solClient_returnCode rc;

rc = solClient_session_sendRequest

( session_p, msg_p, &replyMsg_p );

The SEMP response is returned in the Reply Message.
Obtain the binary attachment data from the Reply Message:
solClient_msg_getBinaryAttachment

(reply Msg_p, byteOutputBuffer, sizeof ( byteOutput Buffer );

The binary attachment contains the SEMP response for the command topic in the publish request.

For API specifications and more details, refer to Products.

Publishing SEMP Requests with the .NET API

To publish a SEMP request with the Solace .Net Messaging API, perform the following steps:

Create a Session.
Create the message topic.
“#SEMP/<router name>/<cmd-topic>”

ITopic topic =

ContextFactory.Instance.CreateTopic(topicString);
Create a request message and set its Destination to the topic in Step 2:
IMessage requestMsg = ContextFactory.Instance.CreateMessage();

requestMsg.Destination = topic;
Set the SEMP request string as the binary attachment:
requestMsg.BinaryAttachment = byteInputBuffer;
Call the SendRequest(…) method on Session.
IMessage replyMsg;

ReturnCode rc = session.SendRequest(requestMsg, out replyMsg, timeout);

The SEMP response is returned in replyMsg.
Obtain the binary attachment data from the reply message:
replyMsg.BinaryAttachment

The binary attachment contains the SEMP reply for the command topic in the publish request.

For API specifications and more details, refer to the Products.

Receiving SEMP Replies Over the Message Bus

Client applications can handle SEMP replies over the message bus as they would other Direct messages—through a message receive interface (XMLMessageConsumer for the JCSMP), a message receive callback (C API), or a delegate (.NET API) that are set when the Session is created.

For information on how to receive messages with the messaging APIs, refer to Receiving Direct Messages.

Generating Java SEMP APIs

If you want to integrate SEMP into your Java applications, you can use tools from the Java Architecture for XML Binding (JAXB) project to generate a Java SEMP API. Using the third-party tool, you can create a set of Java classes from the SEMP XML schema that can be imported into Java applications. With those Java classes, your Java applications can create object-oriented SEMP request commands and decompose SEMP replies into Java objects.

To convert the Solace SEMP XML request and reply schemas to Java class files, the JAXB binding files for SEMP requests (semp-rpc-soltr-jaxb-bindings.xsd) and SEMP replies (semp-rpc-reply-soltr-jaxb-bindings.xsd) that are provided with the software release bundle must be specified when running the JAXB generation tool.

To generate a Java SEMP API, perform the following:

Go to https://jaxb.java.net/ and download the latest release of JAXB.
Follow the instructions provided by the JAXB project to properly install the toolset.
Convert SEMP command schema.
In the JAXB conversion tool , enter the following command:
- xjc -p SolaceSempRequest semp-rpc-soltr.xsd -b semp-rpc-soltr-jaxb-bindings.xsd
  The tool will create a SolaceSempRequestdirectory in the current directory. The new directory contains Java class files that represent the SEMP request commands.
Convert SEMP reply schema.
In the JAXB conversion tool, enter the following command:
- xjc -p SolaceSempReply semp-rpc-reply-soltr.xsd -b semp-rpc-reply-soltr-reply-jaxb-bindings.xsd
  The tool will create a SolaceSempReply directory in the current directory. The new directory will contain Java class files that represent the SEMP reply commands.
  
  For more information on how to import and use JAXB-generated APIs, go to https://jaxb.java.net.