JoeSNMP FAQ

$Id: FAQ.txt,v 1.2 2004/10/07 14:09:40 andd Exp $

(Note: needs updating after joeSNMP became a separate sourceforge project)

------------------------------------------------------------------------------

What license is JoeSNMP released under?

	JoeSNMP is released under the GNU Lesser General Public License (LGPL), 
	documented fully at http://www.fsf.org/copyleft/lesser.html.
	Effectively, this means that JoeSNMP is free to distribute and modify as 
	long as you provide your modified code back to the community.  And if
	you'd like to use JoeSNMP as a library within your commercial product,
	you are welcome to do so as well, but again, any changes to the
	library itself need to be contributed back.  

------------------------------------------------------------------------------

What does "JoeSNMP" stand for?

	JoeSNMP stands for "Java SNMP". In short it is a completely "free"
	implementation of the SNMP protocol written entirely in Java. The 
	currently supported version is for Java 1.2 and greater. The
	code base includes classes that are part of the 1.2 standard that are
	not supported in version 1.1 or 1.0 of JAVA.
	
	The number of JAVA 1.2 specific classes used are relatively small, and
	with minor modification the JoeSNMP source could be tweaked to support
	Java 1.1 or earlier as needed.

	JoeSNMP has been built and tested under the Java2 SDK from Sun.  It should
	work in any Java2-compliant JRE, but our testing is not complete.  

------------------------------------------------------------------------------

Where do I get the latest copy of the source?

	JoeSNMP is distributed as part of OpenNMS.

	The latest copy of the source can be retrieved from the development CVS
	tree at cvs.sourceforge.net/opennms.   Note that the most stable releases of the 
	code will be available from the OpenNMS web site 
	(http://www.opennms.org) and that code in the CVS tree is truly under 
	development, so it may or may not work at any given point in time.

	To get the code from the CVS server you will need a CVS client and the 
	following information:
	
    User ID:   anonymous
    Password:  anonymous
    CVSROOT:   :pserver:anonymous@cvs.sourceforge.net:/cvsroot/opennms

    Module: opennms
		
	Example Checkout:
	
    (Issue the following command:)
    cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/opennms -z3
	co opennms
		
	Now you have the source in the directories JoeSNMP & jcommon. The next 
	step is to build the source and code away.
	
------------------------------------------------------------------------------

What version of the SNMP protocol are supported by JoeSNMP?

	JoeSNMP supports SNMP protocol versions 1 and 2c. SNMPv2c is the 
	community-based branch of the SNMPv2. No support is planned for any 
	other version of SNMPv2, but feel free to add that support if you like.
	
	SNMPv3 support is planned for a future release of JoeSNMP.  And again, 
	if you'd like to start building that right away, knock yourself out.  
	But let us know, so we aren't duplicating efforts.  We hate it when 
	that happens.

------------------------------------------------------------------------------

Why another JAVA SNMP stack?

	Simply put, we couldn't find a free, functional, GPL-friendly stack that
	already existed. In order to accompish the goals for OpenNMS.org (which
	are numerous, lofty, and well worth checking out at 
	http://www.opennms.org) we needed one and resorted to building it 
	ourselves.
	
	There are a few vendors that provide commercial SNMP stacks, but
	these were not compatible with our Open Source approach. Another 
	option for SNMP in Java would have been Sun's JMX (Java Management 
	eXtension), however the final JMX specification was still not finished 
	and/or published as of this writing in June 2000.
	
------------------------------------------------------------------------------

Is the library a "clean room" build, or is it based off of previous work?

	In order to write the JoeSNMP library a lot of effort was put into looking
	at existing SNMP frameworks. The language that could be considered to be
	the closest to Java, C++, was a prime target for finding existing code.
	One of the first libraries we stumbled across was the SNMP++ code 
	released by Hewlett-Packard (HP) and developed by Peter Erik Mellquist. 
	
	Mellquist's implementation is certainly solid, and we wanted to leverage
	the best parts of his design, without leveraging his code. His structure
	influenced the initial framework of JoeSNMP. The ultimate design and 
	resultant code base were built and written by developers at the 
	N*Manage Company, Inc., which actively supports and contributes to 
	OpenNMS.

------------------------------------------------------------------------------

What do I need to know to use JoeSNMP?

	The first thing you need to know is that the entire library and sample 
	code have all been documented with JavaDoc and any questions you have 
	regarding specific methods can be answered there.  

------------------------------------------------------------------------------

Whoa!  I've got conceptual questions before I get to questions about methods!

	We understand that there are some questions about implementation that 
	you might have.  We'll try to address some of those here.

	JoeSNMP, like other SNMP packages, is based around the concept of an SNMP
	session. A session is a communication channel between the manager and 
	a remote agent. A session encapsulates various parameters like
	community strings, protocol version, and packet encoding. Once a session
	is created the manager code can communicate with the remote agent by 
	sending	requests and waiting for responses.
	
	Each management application requires an object that implements the 
	SnmpHandler interface. The SnmpHandler interface is responsible for 
	processing received SNMP Protocol Data Units (PDU) on behalf of the 
	application. If an error occurs with the sesion then the HANDLER is 
	informed of the error, not the function that created the session.

------------------------------------------------------------------------------

Do I have to set a default SnmpHandler for a session and can I have multiple
handlers for a session?

	No, it is not necessary to set up a default handler for an SnmpSession
	object. However, if a default handler is not specified the application 
	must pass a handler to the send() method for each transmission. If the
	application fails to provide a handler then an exception is thrown 
	when the send() method is called.
	
	Likewise, it is possible to specify a default handler and then use 
	a different handler on a case-by-case basis. There is nothing to 
	prevent a different handler for each request. 
	
	Also, it is possible to have one SnmpHandler that is used
	by all open SnmpSession objects to handle received responses.

------------------------------------------------------------------------------

Is it possible to use one session for all remote agent?

	Nope. Each session is tied to an indiviual agent. If communications
	with multiple agents is required then create a new session for
	each agent.

	And that's what threads are for...
	
------------------------------------------------------------------------------

Why does my application fail to exit when I don't call the close() method
on SnmpSession & SnmpTrapSession?

	Thanks to Java's built-in garbage collection, when programmers are 
	through with objects they can just forget about them. But for some 
	objects, this can be more of a curse than a blessing.

	The JoeSNMP code base relies on the Java language's inherent threading
	to simplify many of the tasks in the JoeSNMP code. Thus, the 
	SnmpTrapSession	and SnmpSession objects create additional threads 
	to do the background I/O required to retransmit and receive messages. 
	If the session's close() method is not called, these threads continue 
	to work, keeping the JAVA Virtual Machine (JVM) from exiting when the 
	session	is no longer referenced.

------------------------------------------------------------------------------

How do I know when to call the close() method so I don't shutdown the 
session while its still communicating?

	There are several good ways to do this, with no one way being the 
	definitive best. The method that we have chosen to use in the 
	example code is to synchronize on the session in question and 
	wait for notification.
	
	When the proper conditions are met, usually in the handler methods,
	the code synchronizes on the session and then the session's notify()
	method is called. When the lock on the session is released the 
	waiting thread can safely call the close() method.
	
	For examples see the code located in the jsnmp module of CVS. The
	path will be jsnmp/org/opennms/test/ and the sample files are
	snmpwalk.java and trapd.java.

------------------------------------------------------------------------------

JoeSNMP has an object hierarchy for adding my own custom SnmpSyntax object.
How do I add a custom object so that the SnmpSession will recognized?

	To add a custom object the object must first implement the SnmpSyntax
	interface. After the object has been defined, call the 
	registerSyntaxObject() method of SnmpSession to add object. The object's 
	typeId() must not conflict with a predefined type, or it will not work 
	correctly.
	
	Once the object has been registered, all new and open SnmpSession 
	objects will be able to send and receive the new syntax type.

------------------------------------------------------------------------------

Is it possible to use different encoding rules other than BER?

	By default all sessions use the Basic Encoding Rules (BER). It is
	possible to change the encoder on a session by session basis. A
	custom encoder must implement the ASNEncoder interface and then
	be registered with the SnmpParameters for the session.
	
	The ASNEncoder interface can be found in the package 
	org.opennms.protocols.snmp.ans1.

------------------------------------------------------------------------------

Who do I blame when the FAQ doesn't answer my question or the code
doesn't work as advertised?

	Well..... Um..... That would be Brian Weaver (A.K.A. Weave or
	"Commander Clueless"). I'm the one responsible for the design,
	developement, and maintance of JoeSNMP and its FAQ.
	
	Constructive criticism, patches, new code, bugs and the like
	can be sent to <weave@oculan.com>. If you wish	to contribute,
	visit the OpenNMS web site (http://www.opennms.org) or
	drop a line to Tarus Balog <tarus@opennms.org>.
	
	All patches or enhancements to the core code MUST be released
	under the LGPL or it will not be accepted for inclusion on the
	OpenNMS.org site. Examples, Documentation, example code and other 
	contributions may be released under the GFDL, GPL, or other license, but
	will not be included in the OpenNMS code repository unless it fits the 
	OpenSource criteria as defined by the OpenSource Initiative
 	(http://www.opensource.org/).

	We prefer the Copyleft, and we hope you do too.

------------------------------------------------------------------------------

People and Organizations that have contributed to the JoeSNMP code base:

	Name	              Organization         Comments
	--------------------  -----------------    --------------------------
	Brian Weaver	      Oculan Corp.  Core developer/maintainer.
	 <weave@oculan.com>
	
	Sowmya Kumaraswamy    Oculan Corp.  Developer
	
	Shivakumar C. Patil   [Individual]	   Testing and example code.
	 <shivakumar.patil@stdc.com>

	Nazario Irizarry, Jr. [Individual]         Testing/Bug fixes
	 <naz@personalgenie.com>
