The session continues when the client application sends a request to the JUNOScript server. The JUNOScript 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:
To initiate a request to the JUNOScript 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:
The application encloses each request in a separate pair of opening <rpc> and closing </rpc> tags. The <rpc> tag element can occur only within the <junoscript> tag element. For an example of emitting an <rpc> tag element in the context of a complete JUNOScript session, see Example of a JUNOScript Session.
The JUNOScript 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 Spaces, Newline Characters, and Other White Space.
See the following sections for further information:
A client application can make three classes of requests:
 |
Note: Although operational and configuration requests conceptually belong to separate classes, a JUNOScript session does not have distinct modes that correspond to CLI operational and configuration modes. Each request tag element is enclosed within its own <rpc> tag element, so a client application can freely alternate operational and configuration requests. |
Operational requests are requests for information about routing platform status and correspond to the CLI operational mode commands listed in the JUNOS Software command references. The JUNOS XML API defines a request tag element for many CLI commands. For example, the <get-interface-information> tag element corresponds to the show interfaces command, and the <get-chassis-inventory> tag element requests the same information as the show chassis hardware command.
The following sample request is for detailed information about the interface called 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 Software release, see the JUNOS XML API Operational Reference.
Requests for configuration information are requests for information about the candidate configuration, a private configuration, or the committed configuration (the one currently in active use on the routing platform). The candidate and committed configurations diverge when there are uncommitted changes to the candidate configuration.
The JUNOScript API defines the <get-configuration> tag element for retrieving configuration information. The JUNOS XML API defines a tag element for every CLI configuration statement described in the JUNOS Software configuration guides.
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 are requests to change the information in the candidate or a private copy, or to commit those changes to put them into active use on the routing platform. The JUNOScript API defines the <load-configuration> tag element for changing configuration information. The JUNOS XML API defines a tag element for every CLI configuration statement described in the JUNOS Software configuration guides.
The following example shows how to create a new JUNOS 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.
Optionally, a client application can include one or more attributes in the opening <rpc> tag for each request. The client application can freely define attribute names, except as described in the following note. The JUNOScript 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 request tag that assigns a unique identifier. The JUNOScript server echoes the attribute in its opening <rpc-reply> tag, making it easy to map the response to the initiating request.
|
Note: The xmlns:junos attribute name is reserved. The JUNOScript 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. |
The JUNOScript server encloses its response to each client request in a separate pair of opening <rpc-reply> and closing </rpc-reply> tags:
<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> tag element. Client applications must include code for parsing the stream of response tag elements coming from the JUNOScript 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> tag element in the context of a complete JUNOScript session, see Example of a JUNOScript Session.
The JUNOScript 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 Software running on the JUNOScript server machine.
In the following example, the namespace corresponds to the initial version of JUNOS Release 10.0:
<rpc-reply xmlns:junos="http://xml.juniper.net/junos/10.0R1/junos">
The JUNOScript server returns three classes of responses:
Operational responses are responses to requests for information about routing platform status. They correspond to the output from CLI operational commands as described in the JUNOS command references.
The JUNOS XML API defines response tag elements for all defined operational request tag elements. For example, the JUNOScript server returns the information requested by the <get-interface-information> tag element in a response tag element called <interface-information>, and the information requested by the <get-chassis-inventory> tag element in a response tag element called <chassis-inventory>.
The following sample response includes information about the interface called ge-2/3/0. The namespace indicated by the xmlns attribute contains interface information for the initial version of JUNOS Release 10.0. (Note that the opening <interface-information> tag appears on two lines only for legibility.)
<rpc-reply xmlns:junos="http://xml.juniper.net/junos/10.0R1/junos">
<interface-information \
xmlns="http://xml.juniper.net/junos/10.0R1/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 are responses to requests for information about the routing platform’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 tag elements for the admin user - ->
</user>
</login>
</system>
</configuration>
</rpc-reply>
Configuration change responses are responses to requests that change or commit routing platform configuration. For commit operations, the JUNOScript server encloses an explicit indicator of success or failure within the <commit-results> tag element:
<rpc-reply xmlns:junos="URL">
<commit-results>
<!- - tag elements for information about the commit - ->
</commit-results>
</rpc-reply>
For other operations, the JUNOScript 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.
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 a 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/ .
If the JUNOScript server encounters an error condition, it emits an <xnm:error> tag element, 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 element 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> tag 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 tag elements enclosed in the <xnm:error> tag element depends on the operation that server was performing when the error occurred:
If the JUNOScript 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>.
To request that the JUNOScript 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 JUNOScript 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 JUNOScript 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/>.
