External Java Applications That Use NIC
If you write an external Java application that interacts with a NIC, include NIC libraries in the application. These libraries are for NIC proxies and local NIC hosts. These libraries are located in the SRC distribution under SDK/lib/nic.
Typically, each NIC resolution process requires one NIC proxy. For example, the OnePopLogin sample data includes two resolution processes:
- Mapping of a subscriber's IP address to the subscriber's login name
- Mapping of the subscriber's login name to the SAE reference
An application that uses both these resolution processes would require two NIC proxies.
The NIC proxy provides a simple Java interface, the NIC application programming interface (API). You configure the NIC proxy to communicate with one resolver. For efficiency if you use NIC in client/server mode, the NIC proxy caches the results of resolution requests so it can respond to future requests for the same key without contacting the resolver.
The SRC software includes a factory interface, the NIC factory, to allow applications to instantiate, access, and remove NIC proxies. It also includes JAR files for NIC client and NIC host libraries.
Developing a Java Application to Communicate with a NIC Proxy
You must configure an application to communicate with a NIC proxy.
If you are using Java Runtime Environment (JRE) 1.3 or higher, you must include in your application the Java archive (JAR) files, which are in the SRC software distribution in the folder /SDK/lib/ with your application:
Configuration tasks that use the API calls to communicate with the NIC proxy are:
- Instantiating a Configuration Manager
- Passing a Reference to the Configuration Manager to the NIC Factory
- Instantiating the NIC Factory Class
- (Optional) Initializing Logging
- Instantiating the NIC Proxy
- Managing a Resolution Request
- Deleting Invalid Results from the NIC Proxy's Cache
- Removing the NIC Proxies
For more information about the API calls, see the online documentation in the SRC software distribution in the folder /SDK/doc/nic or on the Juniper Networks Web site at
http://www.juniper.net/techpubs/software/management/sdx/api-index.htmlInstantiating a Configuration Manager
The application must instantiate a configuration manager.
To enable the application to instantiate a configuration manager to obtain a NIC instance from the NIC factory:
- For some applications (other than Web applications), in which you must define the system property -DConfig.bootstrapFilename, you can call the following method:
ConfigMgr configMgr = ConfigMgrFactory.getConfigMgr();For Web applications, you can instantiate the configuration manager as follows: ConfigMgr configMgr = ConfigMgrFactory.getConfigMgr(properties);
- properties—java.util.Properties object, typically the bootstrap file, which contains all the configuration properties for the NIC proxy.
Passing a Reference to the Configuration Manager to the NIC Factory
To pass a reference to the configuration manager to the NIC factory class:
NicFactory.setConfigManager(configMgr);Instantiating the NIC Factory Class
The way you instantiate the NIC factory depends on the object request broker (ORB) configuration:
NicFactory nicFactory = NicFactory.getInstance();This code instantiates a new NIC factory. Unless the NicFactory.destroy method has been called, subsequent calls to this method will return the instantiated NIC factory.
NicFactory.initialize(props);NicFactory nicFactory = NicFactory.getInstance();
- props—java.util.Properties object, which contains the ORB properties for the NIC proxy. For example, if the NIC proxy uses JacORB but JacORB is not the default ORB, the ORB properties are:
org.omg.CORBA.ORBClass=org.jacorb.orb.ORBorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingletonThis code will instantiate a new NIC factory using the specified ORB. Unless the application has called the NicFactory.destroy method, subsequent calls to the getInstance() method will return the instantiated NIC factory. However, if the application has called the destroy() method, it must recall the initialize() method before it can call the getInstance() method.
For information about the NicFactory.destroy method, see Removing the NIC Proxies.
Initializing Logging
You must initialize logging only if you want to view the logging information produced by the NIC proxy.
To enable the application to initialize logging:
Log.init(configMgr, configNameSpace);
- configMgr—Instance of the configuration manager, the value returned from the getConfigMgr() method
- configNameSpace—String that specifies the configuration namespace where you defined the logging properties
Log.init(configMgr, "/");If you define the logging properties in the directory, specify the namespace relative to the property Config.net.juniper.smgt.lib.config.staticConfigDN, which you configure in the bootstrap file. Log.init(configMgr, "/Applications/Quota");Instantiating the NIC Proxy
To enable the application to instantiate a NIC proxy:
NIC nicProxy = nicFactory.getNicComponent(nicNameSpace, configMgr)Alternatively, if the expected data value (specified for the property nic.value in the NIC proxy configuration) is an SAE reference, you can call the following method:
SaeLocator nicProxy = nicFactory.getSaeLocator(nicNameSpace, configMgr);
- nicFactory—Instance of the NIC factory
- nicNameSpace—String that specifies the configuration namespace where you defined the properties for the NIC proxy
NIC nicProxy = nicFactory.getNicComponent("/", configMgr)If you define the properties in the directory, specify the namespace relative to the property Config.net.juniper.smgt.lib.config.staticConfigDN, which you specified in the bootstrap file. NIC nicProxy = nicFactory.getNicComponent("/Applications/Quota", configMgr)Managing a Resolution Request
To enable the application to submit a resolution request and obtain the associated values:
- Construct a NicKey object to enable the application to pass the data key to the NIC proxy:
NicKey nicKey = new NicKey(stringKey);For the syntax of allowed data types, see Chapter 17, NIC Resolution Process.
- If the resolution process specifies constraints that you wish to provide in the resolution request, add them to the NicKey object:
NicKey.addConstraint(constName, constValue);For the allowed data types and their syntax, see Chapter 17, NIC Resolution Process.
For the allowed syntax for the data types, see Chapter 17, NIC Resolution Process.
For example, you can call a method specified in the NIC interface:
NicValue val = nicProxy.lookupSingle(nicKey);Alternatively, if the expected data value is an SAE reference, you can call the following method:
SaeId saeId = nicProxy.lookupSae(nicKey);
- Call the getValue method to access the string representation of the data value obtained by the NIC proxy.
String val=val.getValue();Alternatively, if the expected data value is an SAE reference:
String val=saeId.getValue();
- Call the getIntermediateValue method if the application expects only one value. This method takes the name of a data type and returns as a string the first value it finds.
String getIntermediateValue(String dataTypeName){};For information about data types, see Chapter 17, NIC Resolution Process.
- Call the getIntermediateValues or getAllIntermediateValues method if the application expects multiple values. These methods take the name of a data type and return values as follows:
String[] getIntermediateValues(String dataTypeName){};For information about data types, see Chapter 17, NIC Resolution Process.
- The getAllIntermediateValues method returns a map of all intermediate values for the request. The key for the map is the name of the network data type, and the value of the map is a string array of the intermediate values.
Map getAllIntermediateValues();Deleting Invalid Results from the NIC Proxy's Cache
If the application receives an exception when using values that the NIC proxy returned for a specific key, it must inform the NIC proxy to delete this entry from its cache.
To enable the application to inform the NIC proxy to delete an entry from its cache:
nicProxy.invalidateLookup(nicKey, nicValue);
- nicKey—Data key that you want to remove from the cache
- nicValue—Optional data value that corresponds to this key
If the application passes a null data value to the NIC proxy, the NIC proxy removes all the values associated with the data key from its cache.
Removing the NIC Proxies
Make sure that before your application shuts down, it removes the NIC proxy instances to release resources for other software processes.
To remove one NIC proxy instance:
NicProxy.destroy();To remove all NIC proxy instances, call the following method:
NicFactory.destroy();