JOTS is a Java library that allows creation of a SNMP interface from Java Objects.

Section
1. Getting started
2. Notes on Tree creation
3. How sets and gets are performed

1. Getting started

1.1 Tree without MIB generation

Creating a tree without a MIB is fairly straight-forward. See section 2.1  to see what fields get included in the generated tree.

	public class SomeObject {
		int fieldOne;
		String fieldTwo;
		final SomeObjectType fieldThree;
		...
	}
	
	SomeObject obj = new SomeObject();
	int[] prefix = new int[] { 1, 3, 6, 1, 4, 1, <some OID> };
	
	SnmpTree tree = TreeBuilder.from(obj).prefix(prefix).build();

1.2 Building a MIB

Creating a MIB can be done by:

	ByteArrayOutputStream mibOutputStream = new ByteArrayOutputStream();

	SomeObject obj = new SomeObject();
	String mibName = "TEST";
	String rootName = "test";
	String parentName = "enterprises";
	int[] prefix = new int[] { 1, 3, 6, 1, 4, 1, <some OID> };
	
	OutputStream os = new ByteArrayOutputStream();
	
	TreeBuilder.from(obj).prefix(prefix)
				.buildMib(mibName, rootName, parentName, os);
		
	// Do something with the OutputStream, such as print it to a file

1.3 Interaction with SNMP4j

1.3.1 Snmp Agent

At this point, you have an SnmpTree object that lets you do gets and sets. The next step is getting an SNMP agent working. JOTS has an implementation using SNMP4J. Creating your own using a different SNMP library should not be too difficult to integrate instead though.

A SNMP agent can be started using an SnmpTree with the following code:

	InetSocketAddress agentAddress = new InetSocketAddress("0.0.0.0", 8161);
	SnmpAgent agent = new SnmpAgent(tree, agentAddress, SnmpAgent.Protocol.udp);

1.3.2 Snmp Trap Receiver

Creating a trap receiver is done in a similar way to creating an agent. For example, if you want to simply set every trapped OID back into your tree (say you are mirroring subtree on a different Agent), you could do:

	InetSocketAddress agentAddress = new InetSocketAddress("0.0.0.0", 8162);
	SnmpTrapReceiver receiver = new SnmpTrapReceiver(tree, agentAddress, SnmpAgent.Protocol.udp) {
	  @Override
	  protected void processTrap(CommandResponderEvent request)
	  {
	    for (VariableBinding vb : request.getPDU().getVariableBindings())
	      tree.set(vb.getOid(), vb.getVariable().toString(), true);
	  }
	}

1.4 Tables

SNMP tables map to Java collections (Maps and Lists). Currently, there is no way to track changes to the collections, so changes will not be tracked after tree creation. If new entries are added to any collection in the tree hierarchy, the tree must be recreated.

As a limited workaround, SnmpAgent does support replacing the SnmpTree. This can be done using the public void updateTree(SnmpTree tree) method. Note that this may cause odd behavior for in-flight partial requests, such as from an snmp walk. All currently requests currently processing must complete before the change takes place.


2. Notes on Tree creation

2.1 Fields

By default, Fields are either included or skipped either through modifiers or annotations. The first condition encountered in the following list determines whether the field is included or skipped.

* Include if annotated with {@link SnmpInclude}
* Exclude if annotated with {@link SnmpExclude}
* Exclude if the field is static
* Exclude if the field is transient
* Include if the field is primitive, a primitive wrapper, String or Enum
* Exclude if the field is not final
* Include

This behavior can be changed by setting the inclusion strategy for the TreeBuilder using the inclusionStrategy method.

2.2 MIB creation

Annotations on fields can be used to generate comments for a generated MIB file. For example, given the following object:

public class SomeObject {
	@BooleanInterfaceComment(
		synopsis = "The status of Foo",
		falseSynopsis = "Foo is disabled",
		trueSynopsis = "Foo is enabled")
	boolean fooStatus;
}
  
the following  will appear in the generated MIB:

FooStatus OBJECT-TYPE
	SYNTAX		Boolean
	MAX-ACCESS	read-only
	STATUS		current
	DESCRIPTION
		"The status of Foo
		 'true'  -> Foo is enabled
		 'false' -> Foo is disabled"
	::= { RootEntry 1 }
	
	
3. How Sets and Gets Are Performed

3.1 OID lookups

When supplying an OID for a SNMP get/set, the field first needs to be looked up in the tree. This is done by peforming a binary search across all the fields in the tree, giving it a complexity of O(log n). OIDs for gets/sets are cached by a controllable cache size for each SnmpTree.

3.2 Get Methods

3.2.1 Get

When an OID is requested, the value from the field corresponding to that OID is returned directly. That is, the corresponding getter, if any, is not used.

3.2.2 Getnext / Walk

Use of snmp walks is discouraged due to poor performance in comparison to bulkwalk. Each getnext operation requires a lookup in the tree, which is a O(log n) operation, making a snmpwalk O(m log n), where m is the number of entries in the requested subtree and n is the number of elements in the tree. In comparison, each bulkget only needs to do a single O(log n) lookup, followed by O(1) access for each subsequent entry resulting in a complexity of O(m + log n).

Unlike get, getnext lookups are not cached. This is because a single walk could easily invalidate the entire cache for the SnmpTree. A separate cache is not maintained since it could significantly impact performance.

3.3 Set Methods

For fields with a setter method, that method is used when peforming sets. Setters are single argument methods with the argument being the same type as the field. The name of the setter must be "set" followed by the name of the field, with the first letter capitalized. For example, a field named "count" would have a setter called "setCount".

If a field does not have a setter or has the SnmpNotSettable annotation, then the field is treated as not being settable. The max-access property in the corresponding generated MIB will be read-only.