9.0 SNMP Table Handling in Generated Code

9.1 Overview
9.2 Storing the Tabular Data

9.1 Overview

This section describes the code generated for tables using different storage models. Firstly, it is required to know how the data of a table are stored in the agent.

9.2 Storing the Tabular Data

The data given in tables can be stored in two formats, either in Agent Table Model or in Your Own Storage Model.

9.2.1 Agent Table Model

Agent Table Model is the default storage model provided by Agent Toolkit. As per this storage model,

For every row in the table, an xxxEntry object gets created.

The xxxEntry object stores the values of all the columns of that single row.

This xxxEntry object has getter and setter methods for getting and setting the value of a particular column.

It also stores the instance OID of the row as an int array. Instance OID is nothing but the index value of a table that identifies a particular row.

All the xxxEntry objects are then put into an AgentTableModel.

The ' AgentTableModel ' internally stores all the xxxEntry objects in a vector sorted by their instance.

The figure given below illustrates how the data are stored in AgentTableModel.

9.2.1.1 Methods Generated for Agent Table Model

The Request Handler file has the following lines generated for a table.

For Getting an xxxEntry from Agent Table Model

The following method is called. This would return the xxxEntry corresponding to the specified instance.

tModelComplete.get(inst);

For Getting the First Entry from Agent Table Model

The following method is called. This would return the xxxEntry corresponding to the first row (instance oid) in the table.

tModelComplete.getFirstEntry();

For Getting the Next xxxEntry from Agent Table Model

To get the xxxEntry corresponding to the instance oid immediately after the specified instance oid (inst), the following method is called.

tModelComplete.getNext(inst);

For Creating a New Entry in the Agent Table Model

For creating a new entry in the Agent Table Model,

A new instance of the xxxEntry object is to be created.

The instance OID ( i.e., the index in dotted OID format ) is set in the xxxEntry object by calling xxxEntry.setInstanceOid(instance);

The values of other columns are also set in the xxxEntry object by calling the respective setter methods.

The above created xxxEntry object is added to the AgentTableModel.

The 4 steps given above are repeated for all the rows in the Table.

For Adding the Row to the Agent Table Model

A row is added to the Agent Table Model by calling this method.

tModelComplete.addRow(entry);

9.2.2 User Storage Model

Sometimes, you may prefer to have other storage mechanisms than using the default Agent Table Model. Agent Toolkit also provides an option to implement your own storage model. To acheive this, storage model for tables can be selected as "User Storage".

Follow the given steps to select 'User Storage' for tables from the MIB Compiler UI while generating the agent code,

Select Project->Settings from menu bar. The Settings dialog will pop up.
Select Source Generation-> Storage Model node from the tree in the left frame of the Settings dialog.
To select User Storage Model for tables, select 'User Storage' option from the combo box.
To select the option for individual tables, select the corresponding table from the list in right panel and choose 'User Storage' option from the combo-box provided.
Generate the source.

This generates a XXXTableModelListener class for each table selected using the User Storage option. This class implements the com.adventnet.utils.agent.TableModelListenerExt interface. All the methods that you want to instrument will be listed in this generated file. You can plug-in your implementation here.

If 'User Storage' is used for tables, then in the generated agent code (like XXXRequestHandler class), XXXTableModelListener instance will be used instead of the Agent Table Model instance.

//To return the entry for the given instance oid

public com.adventnet.utils.agent.TableEntry get(int[] inst);

This method gets called when there is a GET request for the table. The request is sent with the instance oid and on identifying the instance, the value is returned for that entry. If no such instance exists or for an invalid entry, a NULL value is returned.

//To return the next entry for the given instance oid

public com.adventnet.utils.agent.TableEntry getNext(int[] inst);

This method gets called when there is a get next request for an instance oid value. In that case the agent searches for the next immediate instance and returns the value of that instance. A NULL value is returned if no such instance exists.

//To return the first entry

public com.adventnet.utils.agent.TableEntry getFirstEntry();

This method gets called when there is a getnext request for the table without any instance oid.

//This method will be called when any entry is to be added

public void addRow(com.adventnet.utils.agent.TableEntry entry)

throws Exception;

This method gets called when there is a SET request that adds a new row to the table, which has the row status.

//This method will be called when any entry is to be deleted

public void deleteRow(int[] inst) throws Exception;

This method gets called when there is a SET request to delete a particular row in the table that is already existing in the table

//To set the vector of TableEntry objects

public void setTableElements(Vector tableElements);

This method gets called when you want to set the table vector elements.

//To get the vector of TableEntry objects

public Vector getTableElements();

This method gets called when you want to get the vector entry objects.

// To modify the rows in the table

public void modifyRow(String instance,Hashtable list,Vector indexList)

This method gets called during the set request for the table. If the row denoted by 'instance' string is already present in the table, that row should be modified using the incoming values. If the row does'nt exist, new row should be created using the incoming arguments

9.3 Initializing Tables Before Agent Start-Up

Any Table is initialized with the default values provided on Agent start-up. The default values for a Table do not get generated unless the "Initialize with Default Values" is checked in the MIB Compiler UI. (Project -> Settings menu -> General Category).

Instead of having the default values, if you prefer your Agent to be started with a Table holding the values you require, the following methods can be utilized. But please note when you instrument the code for the Tables to have specific values, the Agent should be restarted for the changes to take effect.

9.3.1 createAndAddEntry Method

To create a row in the Table, the following methods can be used.

createAndAddXXXEntry or

createAndAddNewXXXEntry

createAndAddXXXEntry

Using this method will add an entry to the Table with the Instance. The method takes all the column values and its instances as inputs and creates the row. The method name and the parameters used will differ according to the Tables used.

For example : The code for creating and adding a new entry in the AapplicationTable of AGENT-SAMPLE-MIB is given below.

aaplicationTableListener.createAndAddAaplicationEntry(new String (".1"), new Integer(1), "agenttoolkit", "5.0", "6/10/2002", new Integer(1));
aaplicationTableListener.createAndAddAaplicationEntry(new String (".2"), new Integer(2), "windows", "2000", "5/5/2000", new Integer(1));

This code should be included in the initSnmpExtension Nodes generated in the Main file.

createAndAddNewXXXEntry

This method is used to create a new entry to the table without specifying the instance. It accepts all the column values as inputs. To create an instance the createInstance method is called. When the instance value is created and the values for the columns exist, the createandAddEntry method is called. This creates a new entry in the Table.

For example : The code for creating and adding a new entry in the AapplicationTable of AGENT-SAMPLE-MIB is given below.

aaplicationTableListener.createAndAddNewAaplicationEntry(new Integer(1), "agenttoolkit", "5.0", "6/10/2002", new Integer(1));
aaplicationTableListener.createAndAddNewAaplicationEntry(new Integer(2), "windows", "2000", "5/5/2000", new Integer(1));

This code should be included in the initSnmpExtension Nodes generated in the Main file.

createInstanceForEntry

This method is used for creating an instance for a Table by taking the index values as inputs. Once the instance is defined, they are given as inputs along with the columnar values and used for creating an entry.

For example : The code for creating an instance in the AapplicationTable of AGENT-SAMPLE-MIB is given below. This method gets generated by default in the AapplicationTableRequestHandler file.

/* This Method is for creating the Instance OID for the AapplicationTable.*/

public String createInstanceForAaplicationEntry(Integer
valueForAaplicationID) {

int [] inst = null;
int [] ins = null;
int insInt = valueForAaplicationID.intValue();
ins = new int[] {insInt};
inst = utils.addIntArrays(inst, ins);
return utils.intArrayToString((int[])inst);
}

9.3.2 setTableVector Method

The setTableVector(Vector) method in xxxRequestHandler enables you to set your own Vector to the Agent. But make sure of the following :

The Vector contains elements of xxxEntry type.

The INSTANCE should be SET using setInstanceOID() in the entries (xxxEntry) in the Vector e.g.,

Vector aapVec = new Vector();

//Here the entry is created newly.

AaplicationEntry aapEntry1 = new AaplicationEntry();

try{

aapEntry1.setInstanceOID(new int[]{1});

aapEntry1.setAaplicationID(new Integer(1));

aapEntry1.setAaplicationName("agenttoolkit");

aapEntry1.setAaplicationVersion("5.0");

aapEntry1.setAaplicationInstallDate("6/10/2002");

aapEntry1.setAaplictionTablestatus(new Integer(1));

}catch(Exception e){

e.printStackTrace();

}

aapVec.addElement(aapEntry1);

//Here the entry is got from the getAaplicationEntryInstance which will be generated

//in the Agent Main File.

AaplicationEntry aapEntry2 = getAaplicationEntryInstance();

try{

aapEntry2.setInstanceOID(new int[]{2});

aapEntry2.setAaplicationID(new Integer(2));

aapEntry2.setAaplicationName("windows");

aapEntry2.setAaplicationVersion("2000professional");

aapEntry2.setAaplicationInstallDate("5/5/2000");

aapEntry2.setAaplictionTablestatus(new Integer(1));

}catch(Exception e1){

e1.printStackTrace();

}

aapVec.addElement(aapEntry2);

aaplicationTableListener.setTableVector(aapVec);

These codes have to be added in the initSnmpExtensionNodes method of the Agent Main file.

9.4 Index Handling

Any Table should have an Index column defined in it. Each row of a Table is identified by its index value. There are various types of Indexing and this topic provides the details of the supported syntax types in indexes and the types of Indexing.

9.4.1 Supported Syntax Types in Index

An Index in a Table can have only the following types of Syntax :-

INTEGER

OCTET STRING

DISPLAY STRING

UNSIGNED32

OBJECT IDENTIFIER

TIMETICKS

IPADDRESS

NETWORKADDRESS

OPAQUE.

COUNTER32

9.4.2 Types of Indexing

An Index of a Table may belong to the category of : Single Index, Multiple Index, Implied Index or External Index. To know what exactly each index means and how they can be defined in the MIB , please refer to Adding a Table topic in Defining a MB section.

9.4.2.1 Single Index

For a Table having single index column, the code gets generated as given below. Assume that the code is generated for ifTable of RFC1213 MIB in requestProcessing Methods. ifTable maintains a single index column namely, ifIndex whose syntax type is Integer,

int [] inst = AgentUtil.getInstance(oid,ifTableOidRep.length + 1);

entry = (IfEntry )tModelComplete.get(inst);

For any Table, the resolve Index method is called. All the SET requests for the Table reaches the Resolve Index method wherein the requests from the Manager are first checked whether such an Instance exists. If a matching instance does not exist then an error is thrown or a new entry is created. The code for resolving index resolves the value of the indices from the instance oid given.

9.4.2.2 Multiple Index

When it comes to a Table having Multiple Index, the code is generated in the same manner. The only change in Multiple Index is that while resolving the Index, the instance and its syntax type are verified.

9.4.2.3 External Index

When a Table has an external index column, then the request for that particular Table should first check if such an index column exists in the Base Table. The presence of external index value is checked by the code generated as follows in the respective Table's Request Handler File, (say for a Table having its first index syntax as Integer)

if(!agentName.checkExternalAaplicationID((Integer )indexVar[0].getVarObject())){

AgentUtil.throwNoSuchInstance();

}

In this code, the agentName is the reference of the SNMP Agent Main file generated for the MIB and the indexVar[1] is the value of the external index from the request Varbind.

The checking for the value present in the External Table is done using the checkExternalXXX method in the Agent Main file as,

public boolean checkExternalXXX(Integer value){

Vector vec = XXXTableListener.getTableVector();

return checkExternalIndex(vec, value);

}

When the entry reaches the Agent with the instance oid value, the resolve index method gets called in the XXXRequestHandler file. The method for the same is,

// Resolving the Index

indexVar = AgentUtil.resolveIndex(inst,type);

if(indexVar == null){

AgentUtil.throwWrongValue(pe.getVersion());

}

int req = node.getSubId();

switch(req){

Based on the instance type, the index is resolved. If the index value is null or if no such instance exists, an error is thrown after resolving the index.

9.4.2.4 Implied Index

A Table having an Implied index column is similar to a Table having Multiple index columns. The code gets generated similar to other Tables. But while resolving the Index, the API call that gets called is,

resolveIndex(int[] inst, byte[] type, boolean[] isImplied)

If isImplied is set to "false", then the Index is resolved taking into consideration the length of the instance. If set to "true", then it is handled in the manner as any Table that has multiple Index columns is handled.

Example

For better understanding of all indexes please go through the example available in <Agent Toolkit Home>/examples/snmp/tablehandling/tables directory. The information in readme.html will help you run the example.