Version 5.0:
23/03/2006

This is version 5.0 of the simple Java SNMPv1, SNMPv2c and SNMPv3 stack.
It can be collected via our homepage:
<URL http://www.westhawk.co.uk/resources/snmp/snmp5_0.zip>        (1.9 Mb)
<URL http://www.westhawk.co.uk/resources/snmp/stubBrowser5_0.zip> (52 K)

Read the file StackUsage.html for general information how to use the stack.
The frequently asked questions can be found in faq.html.

This version is a small add-on to 4_14. 4_14 wasn't released to the public
domain, so hence the new number. 4_14 has a huge amount of changes, so it felt
a major version number incremen was appropriate.

*** New class in package UK.CO.WESTHAWK.SNMP.STACK:
- uk.co.westhawk.snmp.stack.BitsHelper
  Helper methods to the BITS construct



********************************************************************************

Version 4.14:
01/02/2006

We would like to thank everyone that was kind enough to send us bug fixes
and/or useful suggestions:
- Victor Kirk <Victor.Kirk@serco.com>
- Chris Barlock <barlock@us.ibm.com>
- Robert Kostes <rkostes@panix.com>
- Steven Bolton <sbolton@cereva.com>
- Josh Bers <jbers@bbn.com>
- Ian Dowse <iedowse@iedowse.com>

Sorry if we've left anyone out.


********************************************
********************* BUG FIXES ************
********************************************

- Destroying a context no longer creates a listener object that listens for
  incoming traps (or PDUs in general).

- When doing discovery in SNMPv3, the contexts are now destroyed.

- When receiving incoming packets, the value of the outgoing hostaddress is no
  longer overwritten.



********************************************
********************** NEW FEATURES ********
********************************************

- Stack is able to listen for incoming requests (and no longer for traps only).

- Stack is able to listen on multiple ports for requests and traps.

- Contexts (incoming and outgoing) can be bound to a local bind address.

- Released separate package stubBrowser4_14.zip that contains a new and
  experimantal Stub Browser. See documentation.

- In SNMPv3, if the contextEngineID is of length zero, the encoder will use
  the (discovered) snmpEngineId.

- Added support for DateAndTime text convention to AsnOctets.

- Added Printable interface to AsnOctets for users to implement their own
  code.

- Added a MultiSourcePdu that can do broadcast requests. Use with care!

- Build in support for IPv6.

- Build in support for 'Reliable SNMP'. See also 'Known Issues' below.

- Using Ant and no longer make.

- Replaced all shell scripts by Ant targets.

- Restructured the project directories and files (i.e. made src, classes, doc
  and lib directories).



********************************************
********************** KNOWN ISSUES ********
********************************************

- Build in support for 'Reliable SNMP' works with a TCP socket.
  It has limited functionality;
  + You can send requests and get a response,
  + You can receive traps,
  + You can receive requests, BUT it is NOT possible to send a response back.
    This is because the architecture has no facilities (yet) to keep the newly
    created (accepted) Socket and use it to send the response.



********************************************
********************** NEW *****************
********************************************

*** New classes in package UK.CO.WESTHAWK.SNMP.STACK:
- uk.co.westhawk.snmp.stack.SnmpContextv3Discovery
  Special context to do discovery.

- uk.co.westhawk.snmp.stack.SnmpContextv3Basis
  Forms the basis of (existing) SnmpContextv3 and (new)
  SnmpContextv3Discovery.

- uk.co.westhawk.snmp.stack.ListeningContextFace
- uk.co.westhawk.snmp.stack.ListeningContext
- uk.co.westhawk.snmp.stack.ListeningContextPool
  These classes and interface enable the stack to receive packets from
  more than one socket.
  These replace the (now deprecated) DefaultTrapContext.

- uk.co.westhawk.snmp.stack.AsnOctetsPrintableFace
- uk.co.westhawk.snmp.stack.DefaultAsnOctetsPrintable
  The interface and default implementation that is use by AsnOctets to print.

- uk.co.westhawk.snmp.stack.GetPdu
- uk.co.westhawk.snmp.stack.ReportPdu
- uk.co.westhawk.snmp.stack.ResponsePdu
- uk.co.westhawk.snmp.stack.MultiResponsePdu
  Additional PDUs.


*** New classes in package UK.CO.WESTHAWK.SNMP.NET:
- uk.co.westhawk.snmp.net.TCPSocket
  A wrapper class around the standard Socket to enable 'reliable' SNMP.
  See also 'Known Issues' above.

- uk.co.westhawk.snmp.net.StreamPortItem
  A holder class that associates the incoming packet stream with the
  remote port it came from.


*** New classes in package UK.CO.WESTHAWK.SNMP.EVENT:
- uk.co.westhawk.snmp.event.DecodedPduEvent
- uk.co.westhawk.snmp.event.RawPduEvent
- uk.co.westhawk.snmp.event.RawPduListener
- uk.co.westhawk.snmp.event.RawPduReceivedSupport
- uk.co.westhawk.snmp.event.RequestPduEvent
- uk.co.westhawk.snmp.event.RequestPduListener
- uk.co.westhawk.snmp.event.RequestPduReceivedSupport
  These classes and interfaces enable the stack to receive PDU requests as
  well (besides receiving only traps).


*** New class in package UK.CO.WESTHAWK.SNMP.PDU:
- uk.co.westhawk.snmp.pdu.InterfaceGetNextPduStub
  Autogenerated class by the (new) StubBrowser. It forms the basis of the
  (changed) InterfaceGetNextPdu.


*** New class in package UK.CO.WESTHAWK.SNMP.BEANS:
- uk.co.westhawk.snmp.beans.UsmBeingDiscoveredBean
  The bean that handles being discovered by SNMPv3 non-authoritative engines.






********************************************
********************** CHANGES *************
********************************************


*** Compiler:
- Stack now uses JDK 1.4.1 to compile code, generate javadoc and test the stack.
  However, none of the 1.4 specific packages are used (like java.nio).


*** Changes in package UK.CO.WESTHAWK.SNMP.STACK:

- Split up class uk.co.westhawk.snmp.stack.AsnDecoder into:
  # uk.co.westhawk.snmp.stack.AsnDecoderBase
  # uk.co.westhawk.snmp.stack.AsnDecoderv1
  # uk.co.westhawk.snmp.stack.AsnDecoderv2c
  # uk.co.westhawk.snmp.stack.AsnDecoderv3

- Split up class uk.co.westhawk.snmp.stack.AsnEncoder into:
  # uk.co.westhawk.snmp.stack.AsnEncoderBase
  # uk.co.westhawk.snmp.stack.AsnEncoderv1
  # uk.co.westhawk.snmp.stack.AsnEncoderv2c
  # uk.co.westhawk.snmp.stack.AsnEncoderv3


- uk.co.westhawk.snmp.stack.SnmpConstants:
  General changes:
  # Added
    SMI_V2_UINTEGER32 = GAUGE
  # Renamed
    - UINTEGER32 to OBSOLETED_RFC1442_UINTEGER32


- uk.co.westhawk.snmp.stack.AsnObject:
  Changed methods:
  # AsnObject AsnMakeMe(InputStream in, byte t, int len, int pos, int headLength)
    Added constants to switch(type) that enable the stack to build
    incoming request PDUs.
  # int size() now can throw an EncodingException
  # void write(OutputStream out, int pos) now can throw an EncodingException


- uk.co.westhawk.snmp.stack.AsnObjectId:
  Added methods:
  # public AsnObjectId(long[] oida)
  # public long[] getOid()
  # public long[] getSubOid(int beginIndex, int endIndex)

  General changes:
  # AsnObjectId(InputStream in, int len)
  # int size():
    - handle empty OIDs succesfully
  # public String toString(long v[])
    - improved efficiency

  Changed methods:
  # int size() now can throw an EncodingException
  # void write(OutputStream out, int pos) now can throw an EncodingException


- uk.co.westhawk.snmp.stack.AsnOctets:
  Added methods:
  # public AsnOctets(java.util.Calendar cal)
  # public AsnOctets(java.net.Inet4Address, byte type)
  # public java.util.Calendar getCalendar()
  # public String toCalendar()
  # public InetAddress getIpAddress()
  # public static void setPrintable(AsnOctetsPrintableFace obj)
  # public String toString(AsnOctetsPrintableFace face)
  # public String toInternationalDisplayString()
  # public String toInternationalDisplayString(AsnOctetsPrintableFace face)

  Changed methods:
  # public String toString()
    Uses the DefaultAsnOctetsPrintable:
    - AsnOctetsPrintableFace.isPrintable(byte[] value)
      to test if the Octets are printable, and
    - AsnOctetsPrintableFace.toInternationalDisplayString(byte[] value)
      to convert the byte array to a string.
  # public String toDisplayString()
    Uses US-ASCII character set
  # public String toIpAddress()
    Convert to IPv4 or IPv6, depending on addres


- uk.co.westhawk.snmp.stack.SnmpContextBasisFace:
  General changes:
  # Added constant TCP_SOCKET
  See also 'Known Issues' above.

  Added methods:
  # public String getSendToHostAddress()
  # public String getReceivedFromHostAddress()
  # public String getBindAddress()
  # public boolean isDestroyed()
  # public void addTrapListener(TrapListener l, int port)
  # public void addRequestPduListener(RequestPduListener l)
  # public void addRequestPduListener(RequestPduListener l, int port
  # public void removeTrapListener(TrapListener l, int port)
  # public void removeRequestPduListener(RequestPduListener l)
  # public void removeRequestPduListener(RequestPduListener l, int port)
  # public Object clone()
  # public String getHashKey()

  Changed methods:
  # Added parameters Object obj to encodePacket()
  # Renamed:
    (was) public abstract Pdu processIncomingTrap(byte [] message)
    (now) public abstract Pdu processIncomingPdu(byte [] message)


- uk.co.westhawk.snmp.stack.AbstractSnmpContext:
  General changes:
  # class implements RawPduListener (and no longer TrapListener)
  # added (private) variable stopRequested that is used to stop the thread
  # uses ListeningContextPool (and no longer DefaultTrapContext)

  Added methods:
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace

  Changed methods:
  # Added parameter bindAddress (String) to constructor:
    protected AbstractSnmpContext(String host, int port, String bindAddress,
    String typeSocketA)
  # public String getHostAddress()
    is now deprecated, replaced by two new methods above
  # protected void activate()
    - Only starts thread when any PDU is expecting response (see
      Pdu.isExpectingResponse())
    - activate() is no longer called in constructor, but in sendPacket()
  # Renamed:
    (was) protected abstract void ProcessIncomingMessage(AsnDecoder rpdu,
          ByteArrayInputStream in)
    (now) protected abstract void processIncomingResponse(ByteArrayInputStream in)
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace


- uk.co.westhawk.snmp.stack.SnmpContext:
- uk.co.westhawk.snmp.stack.SnmpContextv2c:
  Added methods:
  # public String getHashKey()

  Changed methods:
  # Added parameter bindAddress (String) to constructor.
  # Renamed:
    (was) public abstract Pdu processIncomingTrap(byte [] message)
    (now) public abstract Pdu processIncomingPdu(byte [] message)
    This method is extended so it not only instantiates new Trap objects, but
    also (other) incoming request PDUs.


- uk.co.westhawk.snmp.stack.SnmpContextPool:
  General changes:
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace

  Added methods:
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace
  # public void destroyPool()

  Changed methods:
  # Added parameter bindAddress (String) to constructor.
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace


- uk.co.westhawk.snmp.stack.SnmpContextv2cPool:
  General changes:
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace

  Added methods:
  # public SnmpContextv2cPool(String host, int port, String comm,
    String typeSocket)
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace
  # public void destroyPool()

  Changed methods:
  # Added parameter bindAddress (String) to constructor.
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace


- uk.co.westhawk.snmp.stack.SnmpContextv3Face:
  Added methods:
  # public void setUsmAgent(UsmAgent newAgent)
  # public UsmAgent getUsmAgent()


- uk.co.westhawk.snmp.stack.SnmpContextv3:
  General changes:
  # class now extends the (new) class SnmpContextv3Basis. Most code has moved
  # to the parent class.

  Changed methods:
  # Added parameter bindAddress (String) to constructor.
  # Renamed:
    (was) public abstract Pdu processIncomingTrap(byte [] message)
    (now) public abstract Pdu processIncomingPdu(byte [] message)
    This method is extended so it not only instantiates new Trap objects, but
    also (other) incoming request PDUs.


- uk.co.westhawk.snmp.stack.SnmpContextv3Pool:
  General changes:
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace

  Added methods:
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace
  # see  uk.co.westhawk.snmp.stack.SnmpContextv3Face
  # public void destroyPool()

  Changed methods:
  # Added parameter bindAddress (String) to constructor.
  # see uk.co.westhawk.snmp.stack.SnmpContextBasisFace


- uk.co.westhawk.snmp.stack.PassiveSnmpContext:
- uk.co.westhawk.snmp.stack.PassiveSnmpContextv2c:
  Changed methods:
  # Added parameter bindAddress (String) to constructor.


- uk.co.westhawk.snmp.stack.DefaultTrapContext:
  This class is now deprecated.
  It is replaced by
  # uk.co.westhawk.snmp.stack.ListeningContextFace
  # uk.co.westhawk.snmp.stack.ListeningContext
  # uk.co.westhawk.snmp.stack.ListeningContextPool
  This class extends the (new) ListeningContext class.


- uk.co.westhawk.snmp.stack.UsmAgent:
- uk.co.westhawk.snmp.stack.DefaultUsmAgent:
  Added methods:
  # public long getUsmStatsUnknownEngineIDs()
  # public long public long getUsmStatsNotInTimeWindows()

  Changed methods:
  # Changed signature of setSnmpContext
    (was) public void setSnmpContext(SnmpContextv3 context)
    (now) public void setSnmpContext(SnmpContextv3Basis context)


- uk.co.westhawk.snmp.stack.Pdu:
  Added methods:
  # protected boolean isExpectingResponse()
    Defaults to true
  # protected StringBuffer printVars(String title, Vector vars)

  Changed:
  # protected abstract void new_value(int n, varbind res)
  # protected abstract void tell_them()
    Are no longer abstract
  # Constructor:
    - Wrapped: Incrementing request ID in a synchronized block
    - initialise: answered = false


- uk.co.westhawk.snmp.stack.TimeWindow:
  General changes:
  # Using hostaddres instead of hostname

  Added methods:
  # public String toString()


- uk.co.westhawk.snmp.stack.TrapPduv1:
  General changes:
  # This class is no longer abstract

  Added method:
  # public TrapPduv1(SnmpContextPool con)
  # protected boolean isExpectingResponse()
    This method returns false


- uk.co.westhawk.snmp.stack.TrapPduv2:
  General changes:
  # This class is no longer abstract

  Added method:
  # protected boolean isExpectingResponse()
    This method returns false

- uk.co.westhawk.snmp.stack.InformPdu:
- uk.co.westhawk.snmp.stack.GetNextPdu:
- uk.co.westhawk.snmp.stack.GetBulkPdu:
- uk.co.westhawk.snmp.stack.SetPdu:
  These four classes are no longer abstract



*** Changes in package UK.CO.WESTHAWK.SNMP.PDU:

- uk.co.westhawk.snmp.pdu.UpSincePdu:
- uk.co.westhawk.snmp.pdu.InterfacePdu:
- uk.co.westhawk.snmp.pdu.GetPdu_vec:
- uk.co.westhawk.snmp.pdu.OneGetPdu:
- uk.co.westhawk.snmp.pdu.OneIntPdu:
  There classes now extend GetPdu (and no longer Pdu)

- uk.co.westhawk.snmp.pdu.InterfaceGetNextPdu:
  This class now extends the (new) InterfaceGetNextPduStub.
  Most of the methods have moved to the parent class.

- uk.co.westhawk.snmp.pdu.InterfacesPdu:
  Removed methods:
  # public static int getNumIfs(SnmpContextBasisFace con)

- uk.co.westhawk.snmp.pdu.DiscoveryPdu:
  Extends GetPdu (and no longer Pdu)
  Removed methods:
  # protected void new_value(int n, varbind a_var)
  # protected void tell_them()

- uk.co.westhawk.snmp.pdu.BlockPdu:
  Uses GetBulkPdu for the bulk request (and no longer OneGetBulkPdu)

- uk.co.westhawk.snmp.pdu.OneTrapPduv1:
  This class is now deprecated. Its parent class is no
  longer abstract so can be used.
  Added method:
  # public OneTrapPduv1(SnmpContextPool con)

- uk.co.westhawk.snmp.pdu.OneSetPdu:
- uk.co.westhawk.snmp.pdu.OneTrapPduv2:
- uk.co.westhawk.snmp.pdu.OneInformPdu:
  These classes are now deprecated. Their parent classes are no
  longer abstract so can be used.




*** Changes in package UK.CO.WESTHAWK.SNMP.NET:
- Change methods (in all classes + interface):
  # Added paramter bindAddr (String) to create() method:
    + public void create(int port, String bindAddr)
    + public void create(String host, int port, String bindAddr)

  # Changed signature of receive method: 
    (was) public ByteArrayInputStream receive(int maxRecvSize) throws IOException
    (now) public StreamPortItem receive(int maxRecvSize) throws IOException

- Removed method (in all classes + interface):
  # public String getHostAddress()
  and replaced it by:
  # public String getSendToHostAddress()
  # public String getReceivedFromHostAddress()



*** Changes in package UK.CO.WESTHAWK.SNMP.EVENT:
- uk.co.westhawk.snmp.event.TrapEvent
  This is now extends DecodedPduEvent, i.e. is always a decoded trap.
  None decoded traps are now part of the (new)
  uk.co.westhawk.snmp.event.RawPduEvent

- uk.co.westhawk.snmp.event.TrapReceivedSupport
  This does no longer fires an undecoded trap event, but only decoded ones.
  Changed signature:
  (was) public void fireTrapReceived(Pdu pdu)
  (now) public void fireTrapReceived(Pdu pdu, int hostPort)
  The hostPort indicates the port on which the trap was received



*** Changes in package UK.CO.WESTHAWK.SNMP.UTIL:
- uk.co.westhawk.snmp.util.SnmpUtilities
  Added methods:
  # public static byte longToByte(long l)
  # public static byte[] longToByte(long[] l)



*** Changes in package UK.CO.WESTHAWK.SNMP.BEANS:
- uk.co.westhawk.snmp.beans.UsmDiscoveryBean
  Uses SnmpContextv3 context (instead of SnmpContextv3Pool), which gets
  destroyed when discovery is done.

  Changed methods:
  # Added parameter bindAddr (String) to constructor

- uk.co.westhawk.snmp.beans.SNMPBean
  Added methods:
  # Constructor (String host, String port, String bindaddress, String socketType)
  # public String getBindAddress()
  # public void setBindAddress(String b)
  # public String getSocketType()
  # public void setSocketType(String t)

- uk.co.westhawk.snmp.beans.AscendActiveSessionBean 
- uk.co.westhawk.snmp.beans.DialogChannelStatusBean
- uk.co.westhawk.snmp.beans.OneNTPrintQBean 
- uk.co.westhawk.snmp.beans.OneNTServiceBean 
- uk.co.westhawk.snmp.beans.OneNTSharedResBean
  Added methods:
  # Constructor (String host, String port, String bindaddress)

- uk.co.westhawk.snmp.beans.IsHostReachableBean
  Added methods:
  # Constructor (String host, String port, String bindaddress)
  # public void freeResources()

- uk.co.westhawk.snmp.beans.InterfaceIndexesBean
  Using the (changed) InterfaceGetNextPdu
  Added methods:
  # Constructor (String host, String port, String bindaddress)
  # public Set getInterfaceIndexSet()

- uk.co.westhawk.snmp.beans.AnnexModemStatusBean
- uk.co.westhawk.snmp.beans.NcdPerfDataBean
  Uses GetPdu (instead of OneGetPdu)

  Added methods:
  # Constructor (String host, String port, String bindaddress)

- uk.co.westhawk.snmp.beans.OneInterfaceBean
  Uses InterfaceGetNextPdu (instead of InterfacePdu)

  Added methods:
  # Constructor (String host, String port, String bindaddress)

- uk.co.westhawk.snmp.beans.NTPrintQBean
- uk.co.westhawk.snmp.beans.NTServiceNamesBean
- uk.co.westhawk.snmp.beans.NTSharedResBean
- uk.co.westhawk.snmp.beans.NTUserNamesBean
  Uses GetNextPdu (instead of OneGetNextPdu)

  Added methods:
  # Constructor (String host, String port, String bindaddress)




*** Changes in package UK.CO.WESTHAWK.SNMP.SERVLET:
- uk.co.westhawk.servlet.Interfaces
- uk.co.westhawk.servlet.JeevesInterfaces
  Use the (changed) InterfaceGetNextPdu

- All the servlets use PrintWriter (ServletResponse.getWriter()),
  instead of ServletOutputStream (ServletResponse.getOutputStream()).



*** Changes in package ORG.BOUNCYCASTLE.CRYPTO.*:
- Using version 1.27 (instead of 1.15) of the Bouncy Castle lcrypto API


