Properties

6.3 Properties

The standard code generation templates that come with AgenPro are using several properties to customize the code generation process. Each property consists of a key and a value.

In many cases, the value part is used only for determining whether a property is defined or not (comparable to the #define and #ifdef macros in C++). From a Velocity code generation template you may call

$agenUtils.isDefined(String oid, String key)

to check whether a property is set to yes, true, or an empty string. In that case, true the method returns true, false otherwise. To get the assigned value of a property, you may call

$agenUtils.getProperty(String oid, String key)

The AgenPro API JavaDoc is located in the doc folder of the installation directory and at http://www.agentpp.com/agenpro/doc/index.html.

For more information on these methods see the AgenPro API documentation.

Properties are associated with MIB nodes. The properties associated with a MIB object are also inherited by all children of that MIB node. Inherited properties cannot be removed from a MIB object, but they can be redefined. Nodes with associated properties have an underlined text in the MIB tree as shown by Figure 2.

Figure 2: AgenPro MIB tree with properties set.

The following example illustrates how property assignment works:

The property skip, if defined, instructs AGENT++ and SNMP4J-Agent code generation templates to not generate any code for those objects that skip property is defined for. Thus, in the above example, no code will be generated for objects under the internet node. However, the skip property is redefined with value false for the interfaces node (by actually adding it to the interface node again). This redefinition causes AgenPro to generate code for the objects in that subtree even if their generation had been suppressed for a parent node.

You can define and use any property you like for your own code generation templates or for customized versions of the code generation templates included in AgenPro. For the AGENT++ and SNMP4J-Agent code generation templates there are some standard properties defined that are described in “AGENT++ Code Generation Properties” on page 18 and “SNMP4J-Agent Code Generation Properties” on page 19.

You can put together your own property files with your custom properties and import those at a MIB node. A sample properties file can be found at:

<installation_directory>/templates/agent++v4_0_x/agent++4_0_x.props

In order to customize and fine tune the code generation process, AgenPro provides means to define arbitrary properties for each MIB object in a project. A property (also called attribute) consists of a key and a value string. A property can be assigned to any MIB object with an OID. Once assigned to a MIB object node, the property is also assigned to all its children. The following sections provide additional information about properties and their usage:

Why using properties?
Working with properties (Properties Tab)
Properties used by AGENT++ code generation templates
Properties used by SNMP4J-Agent code generation templates
Reading properties from an existing source file

6.3.1 Properties Tab

With the Properties tab, as its name suggests, properties can be associated with MIB nodes. The most important element of the tab is a table that lists the properties defined for the selected MIB node including any inherited properties. The first column of the table contains the OID (object name) of the MIB node that originally defined the property. The table is always sorted by the OID column first. The second column contains the keys/identifiers of the properties and the third column contains the associated values.

To toggle the value of simple properties that can be enabled or disabled only, open the context menu on the row of the property to change and chose either Enable or Disable.

To view the properties of a MIB node:

1. Select the Properties tab.

2. Select the MIB node whose properties you want to view (edit) in the MIB tree. If there are any properties associated with a node, then this node will have a underlined node name.

To add a property to a MIB node:

1. Follow the steps above to view the properties of the MIB node.

2. Choose Add from the Properties panel.

3. A new row will be appended to the table. The key of the new property is set to <name> and its value is set to <value>.

4. Modify key and value.

To remove a property from a MIB node:

1. Follow the steps above to view the properties of the MIB node.

2. Select the property you want to remove in the property table. You can only select properties that are originally defined for the select MIB node. Inherited properties will not be affected.

3. Choose Remove from the Properties panel.

To remove all properties from a MIB node:

1. Follow the steps above to view the properties of the MIB node.

2. Choose Remove All from the Properties panel.

To import properties from a file:

1. Follow the steps above to view the properties of the MIB node.

2. Choose Import from the Properties panel.

3. Select a plain text file that follows the Java properties file format. That is, each line is formatted as <key>=<value>.

4. Choose Open to assign the properties to the current MIB node.

To export properties to a file:

1. Select a MIB node whose properties you want to export.

2. Select the Properties tab.

3. Choose Export from the Properties panel. A file dialog box will be opened.

4. Enter a file name and choose Save to save the properties.

5. The properties will be saved to a plain text file where one property will be stored per line as <key>=<value>.

To read properties from an existing source file:

1. Select a MIB node for which you want to read the properties (for example, the root node).

2. Select the Properties tab.

3. Choose From Source from the Properties panel. A file dialog box will be opened.

4. Select an implementation file containing source code generated by AgenPro.

5. The properties that can be identified from the source file will be added to the properties of the currently selected node.

6.3.2 AGENT++ Code Generation Properties

AgenPro provides sets of code generation templates to generate program code for AGENT++ and AgentX++. Please use the most recent version of the templates that can be used with you version of AGENT++. The version of the templates indicates the earliest AGENT++ release with which those templates can be used. Examples:

If your AGENT++ version is < 3.5.10 then you will have to use the AGENT++v3.5 templates.
If your AGENT++ version is 3.5.10 or later then you should use the AGENT++v.3.5.10 templates.
For new projects you should use the agent++v4_0_x.prj project from the projects directory.

The following properties control the code generation for AGENT++. To enable a property, add it to the properties table of a MIB node and assign a value true or yes to it. Then the property will be activated for that MIB node and all its children (unless it has been redefined for a child).

Table 1: Code generation properties for AGENT++ templates.
Property Key	Description
agentX	Enables code generation for AgentX++ subagents. This option must not be defined for AgentX++ master agents.
agentXSharedTables	Tables are generated as AgentXSharedTable subclasses that support index allocation for shared tables. This option must not be used when the agentX option is not set!
lightTables	With this attribute set, read-only columnar objects are not generated as classes but instantiated directly as instances of MibLeaf. This option reduces code size.
tableAsComplexEntry	With this attribute set, tables are generated as subclasses of MibComplexEntry rather than as subclass of MibTable. Use this option for large tables with database or proxy interface.
simulation	Generates a simulation agent where all objects may be modified when the agent is in configuration mode (see also the AGENTPP-SIMULATION-MIB), regardless whether they are read-only or not. This allows easy testing of your management software.
withModuleName	Generates object names with the MIB module name as prefix. This option can be used to avoid name clashes when two (or more) MIB modules use the same name for different objects.
leafSuperClass	Specifies the class name for leaf objects' super class. The default is 'MibLeaf'. This property may be defined to derive all leaf objects from a customized subclass implementation of MibLeaf.
tableSuperClass	Specifies the class name for table objects' super class. The default is 'MibTable'. This property may be defined to derive all table objects from a customized subclass implementation of MibTable.
sharedTableSuperClass	Specifies the class name for AgentX shared table objects' super class. The default is 'AgentXSharedTable'. This property may be defined to derive all table objects from a customized subclass implementation of AgentXSharedTable.
complexEntrySuperClass	Specifies the class name for complex table objects' super class. The default is 'MibComplexEntry'. This property may be defined to derive all table objects of complex type from a customized subclass implementation of MibComplexEntry. See also “tableAsComplexEntry”.
notificationSuperClass	Specifies the class name for notification (trap) objects' super class. The default is 'NotificationType'. This property may be defined to derive all table objects from a customized subclass implementation of NotificationType.
skip	Set this property to "yes" to exclude all objects in this subtree from code generation. This can be overwritten by nodes in the sub-tree.
useStaticConst	Set this property to "yes" use "static const" constants instead of #define for module wide definitions.

6.3.3 SNMP4J-Agent Code Generation Properties

The following properties control the code generation for SNMP4J-Agent. To enable a property, add it to the properties table of a MIB node and assign a value true or yes to it. Then the property will be activated for that MIB node and all its children (unless it has been redefined for a child).

Properties with bold key are job properties and only available through calling $agenUtils.getJobProperty in a template.

Table 2: Code generation properties for SNMP4J-Agent.
Property Key	Description
columnSuperClass	Specifies the class name for columnar objects' super class. The default is 'MOColumn' for read-only columns and 'MOMutableColumn' for all other columns. This property may be defined to derive all columnar objects from a customized subclass implementation of MOColumn or MOMutableColumn.
constructorAccess	If not set then a public constructor is generated.Valid other values include protected, private, and an empty string.
cleanup	If set to yes the ManagedObject.cleanup(..) method is overwritten for MOScalar subclasses.
commit	If set to yes the ManagedObject.commit(..) method is overwritten for MOScalar subclasses.
constantAccess	If not set then public OID constants are generated. Valid other values include protected, private, and an empty string.
contexts	A pipe (‚\|‘) separated list of contexts that are supported for object instances in this sub-tree. See also “Simulation Agent” on page 45.
copyrightFooterComment	Generates the value 1:1 into the footer of each generated source file. Supports multi-line values. Available in SNMP4J-Agent 2.2 or later templates.
copyrightHeaderComment	Generates the value 1:1 into the header of each generated source file. Supports multi-line values. Available in SNMP4J-Agent 2.2 or later templates.
factoryColumn	Read-only columns or columns for which this property is set to yes will get created through calling the appropriate method of the MOFactory instance associated with this MIB module.
factoryScalars	Read-only scalars or scalars for which this property is set to yes will get created through calling the appropriate method of the MOFactory instance associated with this MIB module.
get	If set to yes the ManagedObject.get(..) method is overwritten for MOScalar subclasses.
import[.<1-n>]	The import property (properties) define additional imports needed for the module. If more than one import statement is needed the properties can be enumerated by appending a dot and a one based index value.
next	If set to yes the ManagedObject.next(..) method is overwritten for MOScalar subclasses.
noIndexValidator	Set this property to yes to disable generation of index validator anonymous classes. These classes can be used to implement custom index validation, for example, if such a validation cannot fully specified through SMI.
noRowFactory	Set this property to yes to disable generation of a custom MOTableRowFactory class. Otherwise an instance of the DefaultMOMutableRow2PCFactory class will be used to create rows. Using a custom row factory provides public access (getter) methods for the column values named by the columnar object names.
noTableGetter	Set this property to yes to disable generation of a public table getter method that makes a table accessible outside the MIB module class.
noValueValidator	Set this property to yes to disable generation of value validation anonymous classes for scalar and columnar objects.
moFactory	Specifies a non-default MOFactory to be used for the MIB module.
object.<trapName>	Maps an object instance to a trap (name). Because notification and trap type definitions specify which object types are included in a trap, but do not define which instances of that object types, this mapping is needed to be able to generate a (simulated) notification. The instance is identified by its row index value as defined by the corresponding rows property: object.ifDownIf1 1 where ifDownIf is a trap name as defined by a traps property and 1 is the ifIndex index value. See “Simulation Properties” on page 48 for a complete example. If the value of this property is „?“ or is not specified at all, AgenPro will ask for its value, when this trap is simulated.
package	Set this property to the package name of the generated code. Generated files will be placed in directory matching the package name under the output directory provided in the job configuration. Available in SNMP4J-Agent 2.2 or later templates.
reference	The value of this property is used when the useReference property is set to yes and there is no REFERENCE clause for the object type being generated.
rows	The rows property defines the rows that are create for the table(s) in the node‘s sub-tree. The value of the rows property is a pipe symbol (‚\|‘) separated list of row indexes. A row index value consists of sub-index values which are separated by semicolons (‚;‘). A sub-index value itself can be provided either as dotted numeric string (1.3.6.1.4.1) or as string representation of the sub-index value (snmpAdminString). To specify three indexes for the vacmAccessTable, the value of its rows property could be: v3group;;3;authPriv\|v1;v1;1;noAuthNoPriv\|v2c;;2;1
skip	Set this property to yes to exclude all objects in this subtree from the code generation.
staticMOFactory	Set this property to yes to use a static MOFactory. Default is no.
trapDescr.<trapName>	The trapDescr property defines a textual description for a particular notification template. This description is displayed by AgenPro when asking for missing notification payload references while firing this trap. In addition, the description is used to extend the JavaDoc of this notification generation method.
traps	The traps property defines the names of the notification templates used within the simulation agent and for code generation for a particular NOTIFICATION-TYPE. The names are separated by a pipe symbol („\|“). To define two trap templates for the linkDown NOTIFICATION-TYPE, add the following property/value pair on the linkDown node within the IF-MIB: traps linkDownIf_1\|linkDownIf_256 The content of a trap template is then defined by the object property for each OBJECT-TYPE included in the NOTIFICATION-TYPE‘s OBJECTS clause. Because the trapName is also used as method name, it should only contain letters and digits.
useReference	Set this property to yes to let AgenPro generate a link between the OID of the managed object type and the string value of its REFERENCE clause (or the value of the reference property) using a LinkedMOFactory.
value[.rowIndex]	AgenPro uses the ‚value‘ property to generate code that initializes the values of columnar and scalar objects. In addition, this property is used to set initial values for the built-in simulation agent. Like other properties, this property affects (unless overwritten in a sub-node) all OBJECT-TYPE instances in the sub-tree of this node. This property‘s value must match with the SYNTAX clause of the instances. For example, an string value ‚Text‘ cannot be used as value for an OBJECT-TYPE with SYNTAX clause ‚Integer32‘. For columnar objects you need also to define a “rows” property to create row instances and thus the instances for the columnar objects. For each row index, you then have to define the appropriate column value by: value.<rowIndex> where <rowIndex> is the complete index value as defined in the corresponding rows property, for example: value.v3group;;3;authPriv
volatile	If this property is set to yes for a subtree, all objects generated for that subtree will be volatile and thus excluded from persistent storage and ManagedObject serialization. Otherwise the generated objects support ManagedObjectSerializable serialization.

6.3.4 The Code Generated for SNMP4J-Agent

A description of the code generated for SNMP4J-Agent and how to use it is explained by the SNMP4J-Agent-Instrumentation-HowTo.pdf file in the installation directory of AgenPro. The How-To also describes various approaches to instrument a SNMP4J-Agent or -AgentX agent.