Exchanging Information with the Junos XML Protocol Server

The session continues when the client application sends a request to the Junos XML protocol server. The Junos XML protocol server does not emit any tag elements after session initialization except in response to the client application’s requests. The following sections describe the exchange of tagged data:

Sending a Request to the Junos XML Protocol Server

To initiate a request to the Junos XML protocol server, a client application emits the opening <rpc> tag, followed by one or more tag elements that represent the particular request, and the closing </rpc> tag, in that order:

<rpc><!--tag elements representing a request--></rpc>

The application encloses each request in a separate pair of opening <rpc> and closing </rpc> tags. The <rpc> tag can occur only within the <junoscript> element. For an example of emitting an <rpc> tag in the context of a complete Junos XML protocol session, see Example of a Junos XML Protocol Session.

The Junos XML protocol server ignores any newline characters, spaces, or other white space characters that occur between tag elements in the tag stream, but does preserve white space within tag elements. For more information, see XML and Junos XML Management Protocol Conventions Overview.

See the following sections for further information:

Request Classes

A client application can make three classes of requests:

Note: Although operational and configuration requests conceptually belong to separate classes, a Junos XML protocol session does not have distinct modes that correspond to CLI operational and configuration modes. Each request tag is enclosed within its own <rpc> tag, so a client application can freely alternate operational and configuration requests.

Operational Requests

Operational requests are requests for information about the status of a device running Junos OS. Operational requests correspond to the CLI operational mode commands listed in the Junos OS command references. The Junos XML API defines a request tag for many CLI commands. For example, the <get-interface-information> tag corresponds to the show interfaces command, and the <get-chassis-inventory> tag requests the same information as the show chassis hardware command.

The following sample request is for detailed information about the interface ge-2/3/0:

<rpc><get-interface-information><interface-name>ge-2/3/0</interface-name><detail/></get-interface-information></rpc>

For more information, see Requesting Operational Information. For information about the Junos XML request tag elements available in the current Junos OS Release, see the Junos XML API Operational Reference.

Configuration Information Requests

Configuration information requests are requests for information about the device’s candidate configuration, a private configuration, or the committed configuration (the one currently in active use on the switching, routing, or security platform). The candidate and committed configurations diverge when there are uncommitted changes to the candidate configuration.

The Junos XML protocol defines the <get-configuration> operation for retrieving configuration information. The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy.

The following example shows how to request information about the [edit system login] hierarchy level in the candidate configuration:

<rpc><get-configuration><configuration><system><login/></system></configuration></get-configuration></rpc>

For more information, see Requesting Configuration Information. For a summary of Junos XML configuration tag elements, see the Junos XML API Configuration Reference.

Configuration Change Requests

Configuration change requests are requests to change the candidate configuration, or to commit those changes to put them into active use on the device running Junos OS. The Junos XML protocol defines the <load-configuration> operation for changing configuration information. The Junos XML API defines a tag element for every CLI configuration statement described in the Junos OS configuration guides.

The following example shows how to create a new Junos OS user account called admin at the [edit system login] hierarchy level in the candidate configuration:

<rpc><load-configuration><configuration><system><login><user><name>admin</name><full-name>Administrator</full-name><class>superuser</class></user></login></system></configuration></load-configuration></rpc>

For more information, see Changing Configuration Information and Committing a Configuration. For a summary of Junos XML configuration tag elements, see the Junos XML API Configuration Reference.

Including Attributes in the Opening <rpc> Tag

Optionally, a client application can include one or more attributes of the form attribute-name="value" in the opening <rpc> tag for each request. The Junos XML protocol server echoes each attribute, unchanged, in the opening <rpc-reply> tag in which it encloses its response. A client application can use this feature to associate requests and responses by including an attribute in each opening <rpc> request tag that assigns a unique identifier. The Junos XML protocol server echoes the attribute in its opening <rpc-reply> tag, making it easy to map the response to the initiating request. The client application can freely define attribute names, except as described in the following note.

Note: The xmlns:junos attribute name is reserved. The Junos XML protocol server sets the attribute to an appropriate value on the opening <rpc-reply> tag, so client applications must not emit it on the opening <rpc> tag. For more information, see xmlns:junos Attribute.

Parsing the Junos XML Protocol Server Response

The Junos XML protocol server encloses its response to each client request in a separate pair of opening <rpc-reply> and closing </rpc-reply> tags. Each response constitutes a well-formed XML document.

<rpc-reply xmlns:junos="URL"><!-- tag elements representing a response --></rpc-reply>

The xmlns:junos attribute in the opening <rpc-reply> tag defines the default namespace for the enclosed tag elements that have the junos: prefix in their names, as discussed further in xmlns:junos Attribute. The <rpc-reply> tag element occurs only within the <junoscript> element. Client applications must include code for parsing the stream of response tag elements coming from the Junos XML protocol server, either processing them as they arrive or storing them until the response is complete. See the following sections for further information:

For an example of parsing the <rpc-reply> element in the context of a complete Junos XML protocol session, see Example of a Junos XML Protocol Session.

xmlns:junos Attribute

The Junos XML protocol server includes the xmlns:junos attribute in the opening <rpc-reply> tag to define the XML namespace for the enclosed Junos XML tag elements that have the junos: prefix on their names. The namespace is a URL of the form http://xml.juniper.net/junos/release-code/junos, where release-code is the standard string that represents the release of the Junos OS running on the Junos XML protocol server machine.

In the following example, the namespace corresponds to the initial version of Junos OS Release 13.1:

<rpc-reply xmlns:junos="http://xml.juniper.net/junos/13.1R1/junos">

Junos XML Protocol Server Response Classes

The Junos XML protocol server returns three classes of responses:

Operational Responses

Operational responses are responses to requests for information about the status of a switching, routing, or security platform. They correspond to the output from CLI operational commands as described in the Junos OS command references.

The Junos XML API defines response tag elements for all defined operational request tag elements. For example, the Junos XML protocol server returns the information requested by the <get-interface-information> tag in a response tag called <interface-information>, and returns the information requested by the <get-chassis-inventory> tag in a<chassis-inventory> response tag called <chassis-inventory>. Operational responses also can be returned in formatted ASCII, which is enclosed withiin an output element. For more information about formatting operational responses see Specifying the Output Format for Operational Information Requests in a Junos XML Protocol Session.

The following sample response includes information about the interface ge-2/3/0. The namespace indicated by the xmlns attribute contains interface information for the initial version of Junos OS Release 13.1.

<rpc-reply xmlns:junos="http://xml.juniper.net/junos/13.1R1/junos"><interface-information xmlns="http://xml.juniper.net/junos/13.1R1/junos-interface"><physical-interface><name>ge-2/3/0</name><!-- other data tag elements for the ge-2/3/0 interface -??-></physical-interface></interface-information></rpc-reply>

For more information about the xmlns attribute and contents of operational response tag elements, see Requesting Operational Information. For a summary of operational response tag elements, see the Junos XML API Operational Reference.

Configuration Information Responses

Configuration information responses are responses to requests for information about the device’s current configuration. The Junos XML API defines a tag element for every container and leaf statement in the configuration hierarchy.

The following sample response includes the information at the [edit system login] hierarchy level in the configuration hierarchy. For brevity, the sample shows only one user defined at this level.

<rpc-reply xmlns:junos="URL"><configuration><system><login> <user><name>admin</name><full-name>Administrator</full-name><!-- other data tag elements for the admin user --></user></login></system></configuration></rpc-reply>

Configuration Change Responses

Configuration change responses are responses to requests that change the state or contents of the device configuration. For commit operations, the Junos XML protocol server encloses an explicit indicator of success or failure within the <commit-results> tag:

<rpc-reply xmlns:junos="URL"><commit-results><!-- tag elements for information about the commit --></commit-results></rpc-reply>

For other operations, the Junos XML protocol server indicates success by returning an opening <rpc-reply> and closing </rpc-reply> tag with nothing between them, instead of emitting an explicit success indicator:

<rpc-reply xmlns:junos="URL"></rpc-reply>

For more information, see Changing Configuration Information and Committing a Configuration. For a summary of the available configuration tag elements, see the Junos XML API Configuration Reference.

Using a Standard API to Parse Response Tag Elements

Client applications can handle incoming XML tag elements by feeding them to a parser that implements a standard API such as the Document Object Model (DOM) or Simple API for XML (SAX). Describing how to implement and use a parser is beyond the scope of this document.

Routines in the DOM accept incoming XML and build a tag hierarchy in the client application’s memory. There are also DOM routines for manipulating an existing hierarchy. DOM implementations are available for several programming languages, including C, C++, Perl, and Java. For detailed information, see the Document Object Model (DOM) Level 1 Specification from the World Wide Web Consortium (W3C) at http://www.w3.org/TR/REC-DOM-Level-1/ . Additional information is available from the Comprehensive Perl Archive Network (CPAN) at http://search.cpan.org/~tjmather/XML-DOM/lib/XML/DOM.pm .

One potential drawback with DOM is that it always builds a hierarchy of tag elements, which can become very large. If a client application needs to handle only one subhierarchy at a time, it can use a parser that implements SAX instead. SAX accepts XML and feeds the tag elements directly to the client application, which must build its own tag hierarchy. For more information, see the official SAX website at http://sax.sourceforge.net/ .

Handling an Error or Warning

If the Junos XML protocol server encounters an error condition, it emits an <xnm:error> tag , which encloses child tag elements that describe the nature of the error. Client applications must be prepared to receive and handle an <xnm:error> tag at any time. The information in any response tag elements already received and related to the current request might be incomplete. The client application can include logic for deciding whether to discard or retain the information.

The syntax of the <xnm:error> element is as follows. The opening tag appears on multiple lines only for legibility:

<xnm:error xmlns="http://xml.juniper.net/xnm/1.1/xnm" \ xmlns:xnm="http://xml.juniper.net/xnm/1.1/xnm"><!-- tag elements describing the error --></xnm:error>

The attributes are as follows:

The set of child tags enclosed in the <xnm:error> element depends on the operation that server was performing when the error occurred. An error can occur while the server is performing any of the following operations, and the server can send a different combination of child tag elements in each case:

If the Junos XML protocol server encounters a less serious problem, it can emit an <xnm:warning> tag element instead. The usual response for the client application in this case is to log the warning or pass it to the user, but to continue parsing the server’s response.

For a description of the child tag elements that can appear within an <xnm:error> or <xnm:warning> tag element to specify the nature of the problem, see <xnm:error> and <xnm:warning>.

Halting a Request

To request that the Junos XML protocol server stop processing the current request, a client application emits the <abort/> tag directly after the closing </rpc> tag for the operation to be halted:

<rpc><!-- tag elements for the request --></rpc>
<abort/>

The Junos XML protocol server responds with the <abort-acknowledgement/> tag:

<rpc-reply xmlns:junos="URL"><abort-acknowledgement/></rpc-reply>

Depending on the operation being performed, response tag elements already sent by the Junos XML protocol server for the halted request are possibly invalid. The application can include logic for deciding whether to discard or retain them as appropriate.

For more information, see <abort/> and <abort-acknowledgement/>.