Java SDK
SDX NITRO APIs are categorized depending on the scope and purpose of the APIs into system APIs and configuration APIs. You can also troubleshoot NITRO operations.
System APIs
The first step towards using NITRO is to establish a session with the SDX appliance and then authenticate the session by using the administrator’s credentials.
Create an object of the nitro_service class by specifying the IP address of the appliance and the protocol to connect to the appliance (HTTP or HTTPS). You then use this object and log on to the appliance by specifying the user name and the password of the administrator.
Note: You must have a user account on that appliance. The configuration operations that you can perform are limited by the administrative role assigned to your account.
The following sample code connects to an SDX appliance with IP address 10.102.31.16 by using the HTTPS protocol:
//Specify the IP address of the appliance and service type
nitro_service nitroservice = new nitro_service ("10.102.31.16", "https");
//Specify the login credentials
nitroservice.login("nsroot", "verysecret");
<!--NeedCopy-->
Note: Use the nitro_service object in all further NITRO operations on the appliance.
To disconnect from the appliance, invoke the logout() method as follows:
nitroservice.logout();
<!--NeedCopy-->
Configuration APIs
The NITRO protocol can be used to configure the resources of the SDX appliance.
The APIs to configure a resource are grouped into packages or namespaces that have the format com.citrix.sdx.nitro.resource.config.
For example, the NetScaler resource has the com.citrix.sdx.nitro.resource.config.ns package or namespace.
A resource class provides APIs to perform many other operations. These operations can be creating a resource, retrieving resource details and statistics, updating a resource, deleting resources, and performing bulk operations on resources.
Creating a Resource
To create a resource (for example, a NetScaler instance) on the SDX appliance, do the following:
- Set the value for the required properties of the resource by using the corresponding property name. The result is a resource object that contains the details required for the resource. Note: These values are set locally on the client. The values are not reflected on the appliance until the object is uploaded.
- Upload the resource object to the appliance, using the static add() method.
The following sample code creates a NetScaler instance named “ns_instance” on the SDX appliance:
ns newns = new ns();
//Set the properties of the NetScaler locally
newns.set_name("ns_instance");
newns.set_ip_address("10.70.136.5");
newns.set_netmask("255.255.255.0");
newns.set_gateway("10.70.136.1");
newns.set_image_name("nsvpx-9.3.45_nc.xva");
newns.set_profile_name("ns_nsroot_profile");
newns.set_vm_memory_total(new Double(2048));
newns.set_throughput(new Double(1000));
newns.set_pps(new Double(1000000));
newns.set_license("Standard");
newns.set_username("admin");
newns.set_password("admin");
int number_of_interfaces = 2;
network_interface[] interface_array = new network_interface[number_of_interfaces];
//Adding 10/1
interface_array[0] = new network_interface();
interface_array[0].set_port_name("10/1");
//Adding 10/2
interface_array[1] = new network_interface();
interface_array[1].set_port_name("10/2");
newns.set_network_interfaces(interface_array);
//Upload the NetScaler instance
ns result = ns.add(nitroservice, newns);
<!--NeedCopy-->
Retrieving Resource Details
To retrieve the properties of a resource on the SDX appliance, do the following:
- Retrieve the configurations from the appliance by using the get() method. The result is a resource object.
- Extract the required property from the object by using the corresponding property name.
The following sample code retrieves the details of all NetScaler resources:
//Retrieve the resource object from the SDX appliance
ns[] returned_ns = ns.get(nitroservice);
//Extract the properties of the resource from the object
System.out.println(returned_ns[i].get_ip_address());
System.out.println(returned_ns[i].get_netmask());
<!--NeedCopy-->
Retrieving Resource Statistics
An SDX appliance collects statistics on the usage of its features. You can retrieve these statistics using NITRO.
The following sample code retrieves the statistics of a NetScaler instance with ID 123456a:
ns obj = new ns();
obj.set_id("123456a");
ns stats = ns.get(nitroservice, obj);
System.out.println("CPU Usage:" + stats.get_ns_cpu_usage());
System.out.println("Memory Usage:" + stats.get_ns_memory_usage());
System.out.println("Request rate/sec:" +stats.get_http_req());
<!--NeedCopy-->
Updating a Resource
To update the properties of an existing resource on the appliance, do the following:
- Set the id property to the ID of the resource to be updated.
- Set the value for the required properties of the resource by using the corresponding property name. The result is a resource object. Note: These values are set locally on the client. The values are not reflected on the appliance until the object is uploaded.
- Upload the resource object to the appliance, using the update() method.
The following sample code updates the name of the NetScaler instance with ID 123456a to ‘ns_instance_new’:
ns update_obj = new ns();
//Set the ID of the NetScaler to be updated
update_obj.set_id("123456a");
//Get existing NetScaler details
update_obj = ns.get(nitroservice, update_obj);
//Update the name of the NetScaler to "ns_instance_new" locally
update_obj.set_name("ns_instance_new");
//Upload the updated NetScaler details
ns result = ns.update(nitroservice, update_obj);
<!--NeedCopy-->
Deleting a Resource
To delete an existing resource, invoke the static method delete() on the resource class, by passing the ID of the resource to be removed, as an argument.
The following sample code deletes a NetScaler instance with ID 1:
ns obj = new ns();
obj.set_id("123456a");
ns.delete(nitroservice, obj);
<!--NeedCopy-->
Bulk Operations
You can query or change multiple resources simultaneously and thus minimize network traffic. For example, you can add multiple NetScaler SDX appliances in the same operation.
Each resource class has methods that take an array of resources for adding, updating, and removing resources. To perform a bulk operation, specify the details of each operation locally and then send the details at one time to the server.
To account for the failure of some operations within the bulk operation, NITRO allows you to configure one of the following behaviors:
- Exit. When the first error is encountered, the execution stops. The commands that were run before the error are committed.
- Continue. All the commands in the list are run even if some commands fail.
Note: Configure the required behavior while establishing a connection with the appliance, by setting the
onerror param in the
nitro_service() method.
The following sample code adds two ADC appliances in one operation:
ns[] newns = new ns[2];
//Specify details of first NetScaler
newns[0] = new ns();
newns[0].set_name("ns_instance1");
newns[0].set_ip_address("10.70.136.5");
newns[0].set_netmask("255.255.255.0");
newns[0].set_gateway("10.70.136.1");
...
...
...
//Specify details of second NetScaler
newns[1] = new ns();
newns[1].set_name("ns_instance2");
newns[1].set_ip_address("10.70.136.8");
newns[1].set_netmask("255.255.255.0");
newns[1].set_gateway("10.70.136.1");
...
...
//upload the details of the NetScalers to the NITRO server
ns[] result = ns.add(nitroservice, newns);
<!--NeedCopy-->
Exception Handling
The error code field indicates the status of the operation.
- An error code of 0 indicates that the operation is successful.
- A non-zero error code indicates an error in processing the NITRO request.
The error message field provides a brief explanation and the nature of the failure.
The com.citrix.sdx.nitro.exception.nitro_exception class catches all exceptions in the execution of NITRO APIs. To get information about the exception, you can use the getErrorCode() method.
For a more detailed description of the error codes, see the API reference available in the <NITRO_SDK_HOME>/doc folder.