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.
You must 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 a SDX appliance with IP address 10.102.31.16 by using HTTPS protocol:
``` pre codeblock //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”);
Note: You must use the
nitro\_service object in all further NITRO operations on the appliance.
To disconnect from the appliance, invoke the logout() method as follows:
``` pre codeblock
nitroservice.logout();
<!--NeedCopy-->
Configuration APIs
The NITRO protocol can be used to configure 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.<resource_type>. Each of these packages or namespaces contain a class named <resource_type> that provides the APIs to configure the resource.
For example, the NetScaler resource has the com.citrix.sdx.nitro.resource.config.ns package or namespace.
A resource class provides APIs to perform other operations such as 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 new resource (for example, a Citrix ADC 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 till the object is uploaded.
- Upload the resource object to the appliance, using the static add() method.
The following sample code creates a Citrix ADC instance named “ns_instance” on the SDX appliance:
``` pre codeblock 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 Citrix ADC instance ns result = ns.add(nitroservice, newns);
### Retrieving Resource Details
To retrieve the properties of a resource on the SDX appliance, do the following:
1. Retrieve the configurations from the appliance by using the get() method. The result is a resource object.
2. Extract the required property from the object by using the corresponding property name.
The following sample code retrieves the details of all NetScaler resources:
``` pre codeblock
//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
A SDX appliance collects statistics on the usage of its features. You can retrieve these statistics using NITRO.
The following sample code retrieves statistics of a Citrix ADC instance with ID 123456a:
``` pre codeblock 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());
### Updating a Resource
To update the properties of an existing resource on the appliance, do the following:
1. Set the id property to the ID of the resource to be updated.
2. 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 till the object is uploaded.
3. Upload the resource object to the appliance, using the update() method.
The following sample code updates the name of the Citrix ADC instance with ID 123456a to 'ns\_instance\_new':
``` pre codeblock
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 Citrix ADC instance with ID 1:
``` pre codeblock ns obj = new ns(); obj.set_id(“123456a”); ns.delete(nitroservice, obj);
### 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 executed before the error are committed.
- **Continue.** All the commands in the list are executed even if some commands fail.
Note: You must 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 NetScalers in one operation:
``` pre codeblock
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 errorcode field indicates the status of the operation.
- An errorcode of 0 indicates that the operation is successful.
- A non-zero errorcode indicates an error in processing the NITRO request.
The error message field provides a brief explanation and the nature of the failure.
All exceptions in the execution of NITRO APIs are caught by the com.citrix.sdx.nitro.exception.nitro_exception class. 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.