SnmpHibernate Developer Guide(1.0Beta)

Overview
SnmpHibernate is a MIB/Object Mapping framework inspired by Hibernate Project(O/R Mapping framework). It will release EMS/NMS developer from coding tedious SNMP Client code.

Tell Something about the history of the project. I have been developing EMS/NMS products for about 4 years, and most of the products are based on SNMP protocol. I meet many different and proprietary Framework to ease the SNMP client side development, but I am not satisfied with them still. When I using the Hibernate (www.hibernate.org) to code O/R mapping someday, I am very impressed by its simplicity. I decided to use the same architecture to implement MIB/Object mapping for I find a mib table is the same to a database table, and then the project is born in one weekend:)

The project location: SnmpHibernate on Sourceforge

The SNMP Client API we used: SNMP4J project.

License of the project: Apache 2.0 License(Same to SNMP4J project)


Examples
The most efficient way to introduce something is to show samples.


Get/Set MIB2.System Scalars:

1. Write the SystemInfo class and annotate properties of the class with MIB defination.

import java.io.Serializable;

import net.sourceforge.snmphibernate.api.SmiType;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType.Access;

public class SystemInfo implements Serializable {

    @MibObjectType(oid = "1.3.6.1.2.1.1.1.0", smiType = SmiType.DISPLAY_STRING, access = Access.READ)
    public String sysDesc;

    @MibObjectType(oid = "1.3.6.1.2.1.1.2.0", smiType = SmiType.OID, access = Access.READ)
    public String sysObjectID;

    @MibObjectType(oid = "1.3.6.1.2.1.1.3.0", smiType = SmiType.TIMETICKS, access = Access.READ)
    public long sysUpTime;

    @MibObjectType(oid = "1.3.6.1.2.1.1.4.0", smiType = SmiType.DISPLAY_STRING, access = Access.WRITE)
    public String sysContact;

    @MibObjectType(oid = "1.3.6.1.2.1.1.5.0", smiType = SmiType.DISPLAY_STRING, access = Access.WRITE)
    public String sysName;

    @MibObjectType(oid = "1.3.6.1.2.1.1.6.0", smiType = SmiType.DISPLAY_STRING, access = Access.WRITE)
    public String sysLocation;

    public String getSysContact() {
        return sysContact;
    }

    public void setSysContact(String sysContact) {
        this.sysContact = sysContact;
    }

    public String getSysDesc() {
        return sysDesc;
    }

    public void setSysDesc(String sysDesc) {
        this.sysDesc = sysDesc;
    }

    public String getSysLocation() {
        return sysLocation;
    }

    public void setSysLocation(String sysLocation) {
        this.sysLocation = sysLocation;
    }

    public String getSysName() {
        return sysName;
    }

    public void setSysName(String sysName) {
        this.sysName = sysName;
    }

    public String getSysObjectID() {
        return sysObjectID;
    }

    public void setSysObjectID(String sysObjectID) {
        this.sysObjectID = sysObjectID;
    }

    public long getSysUpTime() {
        return sysUpTime;
    }

    public void setSysUpTime(long sysUpTime) {
        this.sysUpTime = sysUpTime;
    }

}

2. Create the ISnmpSession API, and execute Get/Set operation.
ISnmpSession session = null;
try {
    ISnmpClientFacade facade = new Snmp4JClientFacade();
    ISnmpSessionFactory sessionFactory = facade.getSnmpSessionFactory();
    ISnmpTargetFactory targetFactory = facade.getSnmpTargetFactory();
    session = sessionFactory.newSnmpSession(targetFactory.newSnmpTarget("127.0.0.1", 161));
    SystemInfo sysMIB = session.get(SystemInfo.class);
    sysMIB.setSysContact("[e-mail]");
    session.set(sysMIB);
} finally {
    if(session != null) session.close();
}

Get IfTable

1. Write the IfEntry class first

import java.io.Serializable;

import net.sourceforge.snmphibernate.api.SmiType;
import net.sourceforge.snmphibernate.api.annotation.MibIndex;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType;
import net.sourceforge.snmphibernate.api.annotation.MibTable;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType.Access;

@MibTable
public class IfEntry implements Serializable {

    @MibIndex(no = 0, length = 1)
    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.1", smiType = SmiType.INTEGER32, access = Access.READ)
    public int ifIndex;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.2", smiType = SmiType.DISPLAY_STRING, access = Access.READ)
    public String ifDescr;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.3", smiType = SmiType.INTEGER32, access = Access.READ)
    public int ifType;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.4", smiType = SmiType.INTEGER32, access = Access.READ)
    public int ifMtu;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.5", smiType = SmiType.GAUGE32, access = Access.READ)
    public long ifSpeed;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.6", smiType = SmiType.OCTET_STRING, access = Access.READ)
    public byte[] ifPhysAddress;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.7", smiType = SmiType.INTEGER32, access = Access.READ)
    public int ifAdminStatus;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.8", smiType = SmiType.INTEGER32, access = Access.READ)
    public int ifOperStatus;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.9", smiType = SmiType.TIMETICKS, access = Access.READ)
    public long ifLastChange;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.10", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifInOctets;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.11", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifInUcastPkts;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.12", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifInNUcastPkts;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.13", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifInDiscards;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.14", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifInErrors;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.15", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifInUnknownProtos;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.16", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifOutOctets;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.17", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifOutUcastPkts;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.18", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifOutNUcastPkts;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.19", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifOutDiscards;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.20", smiType = SmiType.COUNTER32, access = Access.READ)
    public long ifOutErrors;

    public IfEntry() {}
   
    public IfEntry(int index) {
        this.ifIndex = index;
    }

    public boolean isLoopback() {
        return ifType == 24;
    }

    public int getIfAdminStatus() {
        return ifAdminStatus;
    }

    public void setIfAdminStatus(int ifAdminStatus) {
        this.ifAdminStatus = ifAdminStatus;
    }

    public String getIfDescr() {
        return ifDescr;
    }

    public void setIfDescr(String ifDescr) {
        this.ifDescr = ifDescr;
    }

    public int getIfIndex() {
        return ifIndex;
    }

    public void setIfIndex(int ifIndex) {
        this.ifIndex = ifIndex;
    }

    public long getIfInDiscards() {
        return ifInDiscards;
    }

    public void setIfInDiscards(long ifInDiscards) {
        this.ifInDiscards = ifInDiscards;
    }

    public long getIfInErrors() {
        return ifInErrors;
    }

    public void setIfInErrors(long ifInErrors) {
        this.ifInErrors = ifInErrors;
    }

    public long getIfInNUcastPkts() {
        return ifInNUcastPkts;
    }

    public void setIfInNUcastPkts(long ifInNUcastPkts) {
        this.ifInNUcastPkts = ifInNUcastPkts;
    }

    public long getIfInOctets() {
        return ifInOctets;
    }

    public void setIfInOctets(long ifInOctets) {
        this.ifInOctets = ifInOctets;
    }

    public long getIfInUcastPkts() {
        return ifInUcastPkts;
    }

    public void setIfInUcastPkts(long ifInUcastPkts) {
        this.ifInUcastPkts = ifInUcastPkts;
    }

    public long getIfInUnknownProtos() {
        return ifInUnknownProtos;
    }

    public void setIfInUnknownProtos(long ifInUnknownProtos) {
        this.ifInUnknownProtos = ifInUnknownProtos;
    }

    public long getIfLastChange() {
        return ifLastChange;
    }

    public void setIfLastChange(long ifLastChange) {
        this.ifLastChange = ifLastChange;
    }

    public int getIfMtu() {
        return ifMtu;
    }

    public void setIfMtu(int ifMtu) {
        this.ifMtu = ifMtu;
    }

    public int getIfOperStatus() {
        return ifOperStatus;
    }

    public void setIfOperStatus(int ifOperStatus) {
        this.ifOperStatus = ifOperStatus;
    }

    public long getIfOutDiscards() {
        return ifOutDiscards;
    }

    public void setIfOutDiscards(long ifOutDiscards) {
        this.ifOutDiscards = ifOutDiscards;
    }

    public long getIfOutErrors() {
        return ifOutErrors;
    }

    public void setIfOutErrors(long ifOutErrors) {
        this.ifOutErrors = ifOutErrors;
    }

    public long getIfOutNUcastPkts() {
        return ifOutNUcastPkts;
    }

    public void setIfOutNUcastPkts(long ifOutNUcastPkts) {
        this.ifOutNUcastPkts = ifOutNUcastPkts;
    }

    public long getIfOutOctets() {
        return ifOutOctets;
    }

    public void setIfOutOctets(long ifOutOctets) {
        this.ifOutOctets = ifOutOctets;
    }

    public long getIfOutUcastPkts() {
        return ifOutUcastPkts;
    }

    public void setIfOutUcastPkts(long ifOutUcastPkts) {
        this.ifOutUcastPkts = ifOutUcastPkts;
    }

    public byte[] getIfPhysAddress() {
        return ifPhysAddress;
    }

    public void setIfPhysAddress(byte[] ifPhysAddress) {
        this.ifPhysAddress = ifPhysAddress;
    }

    public long getIfSpeed() {
        return ifSpeed;
    }

    public void setIfSpeed(long ifSpeed) {
        this.ifSpeed = ifSpeed;
    }

    public int getIfType() {
        return ifType;
    }

    public void setIfType(int ifType) {
        this.ifType = ifType;
    }

}

2. Get "IfTable",

ISnmpSession session = null;
try {
    ISnmpClientFacade facade = new Snmp4JClientFacade();
    ISnmpSessionFactory sessionFactory = facade.getSnmpSessionFactory();
    ISnmpTargetFactory targetFactory = facade.getSnmpTargetFactory();  
    ISnmpSession session = sessionFactory.newSnmpSession(targetFactory.newSnmpTarget("127.0.0.1", 161));
    //Get the whole table
    List<IfEntry> list = session.getTable(IfEntry.class);
    //Get the one interface entry by index
    IfEntry entry = session.getByIndex(IfEntry.class, 1);
    //Only get the "ifDescr" property of one entry.
    IfEntry entryWithDescr = session.getByIndex(IfEntry.class, 1, new String[] { "ifDescr" });
    System.out.println(entryWithDescr.getIfDescr());
} finally {
    if(session != null) session.close();
}


Code Structure
There are two binary jars:

The API jar: net.sourceforge.snmphibernate.api_1.1.0.jar
The SNMP4J implementation jar: net.sourceforge.snmphibernate.impl.snmp4j_1.1.0.jar

Your code should only depend on the API jar.


API Introduction
All API interfaces are defined in the package "net.sourceforge.snmphibernate.api" package.  Introduce the important ones below.

ISnmpClientFacade: Facade of the whole SnmpHibernate framework.
//Create SNMP Session Factory.
ISnmpSessionFactory getSnmpSessionFactory();

//Create SNMP Target Factory.
ISnmpTargetFactory getSnmpTargetFactory();

ISnmpSessionFactory: Factory of ISnmpSession

//Create a SNMP Session.
ISnmpSession newSnmpSession(ISnmpTarget target) throws IOException;


ISnmpTargetFactory: Factory of ISnmpTarget

//Create a SNMP Target by Ip
ISnmpTarget newSnmpTarget(String ip);

//Create a SNMP Target by Ip and port. 
ISnmpTarget newSnmpTarget(String ip, int port);


ISnmpTarget: A SNMP Agent hosted on the managed device.

    //SNMP protocol version enums
    int V1 = 0;

    int V2C = 1;

    int V3 = 3;

    //Get SNMP Read Community.
    String getCommunity();

    //Set SNMP read community.
    void setCommunity(String community);

    //Get IP of the managed device.
    String getIp();

    //Set IP of the managed device.
    void setIp(String ip);

    //Get SNMP Port, default is 161
    int getPort();

    //Set SNMP Port, default is 161
    void setPort(int port);

    //Get SNMP protocol version the agent supports.
    int getVersion();

    //Set SNMP protocol version the agent supports.
    void setVersion(int version);

    //Get SNMP write community.
    String getWriteCommunity();

    //Set SNMP write community.
    void setWriteCommunity(String writeCommunity);


ISnmpSession: Core API of SnmpHiberate that is used to execute SNMP operations.
    /**
     * Get scalar group.
     *
     * @param scalarClass class of the Java Value Object that represents one scalar group.
     *
     * @return Return an instance of the class.
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    <T> T get(Class<T> scalarClass) throws IOException,
            SnmpException, SnmpAnnotationException;

    /**
     * Get specified fields of a scalar group.
     *
     * @param scalarClass class of the Java Value Object that represents one scalar group.
     * @param fields specified fields of the scalar object.
     * @return Return an instance of the class that only has the specified attributes
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    <T> T get(Class<T> scalarClass, String[] fields)
        throws IOException, SnmpException, SnmpAnnotationException;
    /**
     * Get a whole mib table.
     *
     * @param entryClass Class of the Java Value Object that represents one mib entry.
     *
     * @return a list of instances of the class.
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    <T> List<T> getTable(Class<T> entryClass) throws IOException,
            SnmpException, SnmpAnnotationException;
  
    /**
     * Get a mib entry by index.
     *
     * @param entryClass Class of the Java Value Object that represents one mib entry.
     * @param indices If there is only one index, this param is the just the object;
     * if there are multiple indices, this param is an array.
     *
     * @return a mib entry with whole properties.
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    <T> T getByIndex(Class<T> entryClass, Serializable indices)
        throws IOException, SnmpException, SnmpAnnotationException;

    /**
     * Get specified fields of a mib entry by index.
     *
     * @param entryClass Class of the Java Value Object that represents one mib entry.
     * @param indices If there is only one index, this param is the just the object;
     * if there are multiple indices, this param is an array.
     * @param fileds specified fields of the mib entry object.
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    <T> T getByIndex(Class<T> entryClass, Serializable indices, String[] fields)
        throws IOException, SnmpException, SnmpAnnotationException;

    /**
     * Set a scalar group or a mib entry.
     *
     * @param object a Java Value Object represents a scalar group or a mib entry.
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    void set(Object object) throws IOException,
            SnmpException,  SnmpAnnotationException;

    /**
     * Create a mib entry.
     *
     * @param entry a mib entry.
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    void create(Object entry) throws IOException,
            SnmpException,  SnmpAnnotationException;

    /**
     * Delete a mib entry.
     *
     * @param entry
     *
     * @throws IOException When IO errors occured while communicating.
     * @throws SnmpException When SNMP errors occured.
     * @throws SnmpAnnotationException Annotaction Error for your Java Value Object.
     */
    void delete(Object entry) throws IOException,
            SnmpException,  SnmpAnnotationException;


Annotation Introduction
Mapping Java Value Object to MIB
SnmpHibernate uses Java Annotation to mapping a property of a Java Value Object to a MIB Object-Type. For examle, the "System" class is mapping to "iso(1).org(3).dod(6).internet(1).mgmt(2).mib-2(1).system(1)" scalar group.

Sytem.java:

import java.io.Serializable;

import net.sourceforge.snmphibernate.api.SmiType;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType.Access;

public class System implements Serializable {

    @MibObjectType(oid = "1.3.6.1.2.1.1.1.0", smiType = SmiType.DISPLAY_STRING, access = Access.READ)
    private String sysDesc;

    @MibObjectType(oid = "1.3.6.1.2.1.1.2.0", smiType = SmiType.OID, access = Access.READ)
    private String sysObjectID;

    @MibObjectType(oid = "1.3.6.1.2.1.1.3.0", smiType = SmiType.TIMETICKS, access = Access.READ)
    private long sysUpTime;

    @MibObjectType(oid = "1.3.6.1.2.1.1.4.0", smiType = SmiType.DISPLAY_STRING, access = Access.WRITE)
    private String sysContact;

    @MibObjectType(oid = "1.3.6.1.2.1.1.5.0", smiType = SmiType.DISPLAY_STRING, access = Access.WRITE)
    private String sysName;

    @MibObjectType(oid = "1.3.6.1.2.1.1.6.0", smiType = SmiType.DISPLAY_STRING, access = Access.WRITE)
    private String sysLocation;

    //don't list the get/set methods here
}

The "@MibObjectType" annotates a class property with MIB defination.

The "IfEntry" class is mapping to "iso(1).org(3).dod(6).internet(1).mgmt(2).mib-2(1).interfaces(2).ifTable(2)" below,

IfEntry.java

import java.io.Serializable;

import net.sourceforge.snmphibernate.api.SmiType;
import net.sourceforge.snmphibernate.api.annotation.MibIndex;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType;
import net.sourceforge.snmphibernate.api.annotation.MibTable;
import net.sourceforge.snmphibernate.api.annotation.MibObjectType.Access;

@MibTable
public class IfEntry implements Serializable {

    @MibIndex(no = 0, length = 1)
    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.1", smiType = SmiType.INTEGER32, access = Access.READ)
    private int ifIndex;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.2", smiType = SmiType.DISPLAY_STRING, access = Access.READ)
    private String ifDescr;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.3", smiType = SmiType.INTEGER32, access = Access.READ)
    private int ifType;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.4", smiType = SmiType.INTEGER32, access = Access.READ)
    private int ifMtu;

    @MibObjectType(oid = "1.3.6.1.2.1.2.2.1.5", smiType = SmiType.GAUGE32, access = Access.READ)
    private long ifSpeed;

    //don't list other properties.
}

"@MibTable" annotatation tags a class as a MIB table.
"@MibIndex" annotates a property as a MIB table index.

MibObjectType: Annotation for mapping a property to a Object-Type of MIB.

@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.FIELD })
public @interface MibObjectType {
    public enum Access { READ, WRITE, CREATE }
  
    String oid();
  
    SmiType smiType();
  
    Access access();
}

MibTable: Annotation for mapping a class to a row of MIB table.
@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.TYPE })
public @interface MibTable {
}

MibIndex:Annotation for mapping a property to an index of MIB table
@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.FIELD })
public @interface MibIndex {

    public static final int VARSTR_WITH_LENGTH = -1;

    public static final int VARSTR_WITHOUT_LENGTH = -2;

    int no(); // index no, 0 start.

    int length(); // length of the index
}

RowStatus: Annotation for mapping the delete/create operations to RowStatus values.
@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.TYPE })
public @interface RowStatus {
    String oid();
    int delete() default 6;
    int create() default 4;
}

Released as OSGi bundle
For I used SnmpHibernate in our product as OSGi bundle, I put the OSGi "Manifest.MF" in the released jars and u could use them on OSGi platform directly.  Sample code below introduce the usage on OSGi:

public Activate implements BundleActivator {

public void start(BundleContext context) throws Exception {
    ServiceReference sRef= context.getServiceReference(ISnmpClientFacade.class.getName());
    ISnmpClientFacade scFacade = context.getService(sRef);
    // then u could inject the fadade to anywhere that need it.
}


public void stop(BundleContext context) throws Exception {
}

}

Advantages
Simplicity: Is it the most simple solution for MIB/Object mapping in the world?

Serializable: Serialize the Java Value Object to anywhere, for example, from Server to client.

To-Do List
Support XML/MIB mapping directly.
Feed new requirements from users.

Contribution
    I hope someone could help me provide an implementation based on WestHawk SNMP protocol stack.

Contact
    [e-mail]