com.outbackinc.services.protocol.snmp
Class SnmpServiceConfiguration

java.lang.Object
  |
  +--com.outbackinc.services.protocol.snmp.SnmpServiceConfiguration

public class SnmpServiceConfiguration

extends java.lang.Object

The SnmpService incorporates a number of optimizations which may improve performance and reduce network load. Some of these enhancements have user-configurable parameters which are accessible via this class. The tunable enhancements and their associated methods are listed below:

Socket send/receive buffer size

setSocketBufferSize(), getSocketBufferSize()

PDU Packing

setBufferDelay(), getBufferDelay()

Clerk Thread Pool

setClerkThreadPool(), getClerkThreadPool()

Time Stamps

setTimeStamps(), getTimeStamps()

Retry packed PDUs

setRetryPackedTimeouts(), getRetryPackedTimeouts()

Trap Queue initial capacity

setTrapQueueCapacity(), getTrapQueueCapacity()

Trap Queue initial expansion size

setTrapQueueExpansion(), getTrapQueueExpansion()

OID Caching

setCachePrunePeriod(), getCachePrunePeriod(),

setCacheExpireFactor(), getCacheExpireFactor(),

setCacheExpireFloor(), getCacheExpireFloor()

Access to the SnmpServiceConfiguration methods may be made through the object returned by the SnmpLocalInterfaces.getServiceConfiguration() method for a service. The following code snippet provides an example:

      SnmpService cSnmpService = SnmpLocalInterfaces.getService();
      SnmpServiceConfiguration cSnmpServiceConfiguration
          = SnmpLocalInterfaces.getServiceConfiguration(cSnmpService);
      cSnmpServiceConfiguration.setBufferDelay(0);
 

The above configurable parameters can be also configured with the following system properties from the command line with the -D option:

jsnmp.socketBufferSize	-	the socket send and receive buffer sizes; default=dependent on Java VM
jsnmp.bufferDelay	-	the amount of time in milliseconds the Shipper delays to accomplish PDU packing; default=20
jsnmp.clerkThreadPool	-	the number of threads available for order delivery; default=10
jsnmp.retrieveTimeStamps	-	add a sysUpTime request to every get/get-next request and return time stamps in returned varbind; default=false
jsnmp.retryPackedTimeouts	-	if a packed PDU times out, break it up into multiple unpacked (single varbind) PDUs and retry with those; default=false
jsnmp.trapQueueCapacity	-	the initial size of the system trap queue; default=1000
jsnmp.trapQueueExpansion	-	the expansion size of the system trap queue; default=500
jsnmp.cachePrunePeriod	-	the period of the cache cleanup thread in seconds; default=30
jsnmp.cacheExpireFactor	-	a variable factor used during cache cleanup; larger values => larger caches; default=2
jsnmp.cacheExpireFloor	-	the minimum lifetime of a cacheable object in seconds; default=60

These additional configurable parameters can be configured with the following system properties from the command line with the -D option:

jsnmp.properties	-	dump all of the configuration parameters and exit
jsnmp.maxClerks	-	the maximum number of clerks (request OIDs per non-atomic request pdu); default=25
jsnmp.ignoreV1V2PduSizeLimit	-	ignore the 484 byte pdu size limit when sending SNMPv1 and SNMPv2 packets; set the pdu size limit to the socket send/receive buffer size (see "socketBufferSize"); default=false
jsnmp.forceGC	-	forces garbage collection at the end of every cache cleanup; default=false
jsnmp.dumpPackets	-	dump incoming and outgoing packets; the system property "outback.trace" must also be set to "trace"; default=false
jsnmp.cacheDisable	-	turn off the cache of retrieved OID values. The SnmpService will use less memory and less CPU with this option enabled; default=false
jsnmp.loadRFC1213MIB	-	whether the RFC1213 MIB will be loaded by the SimpleMIBService. The SimpleMIBService will use less memory with this option disabled; default=true

Method Summary

int	getBufferDelay() Use this method to retrieve the BufferDelay used to pack PDU's.
static boolean	getCacheDisable() Get the current setting of the cacheDisable property.
int	getCacheExpireFactor() Use this method to retrieve the Expire Factor of the cache Pruning task.
int	getCacheExpireFloor() Use this method to retrieve the Expire Floor of the cache Pruning task.
int	getCachePrunePeriod() Use this method to retrieve the period of the cache Pruning task.
int	getClerkThreadPool() Gets the current maximum number of concurrent clerks.
static boolean	getDumpPackets() Get the current setting of the dumpPackets property.
static boolean	getLoadRFC1213MIB() Get the current setting of the loadRFC1213MIB property.
boolean	getRetryPackedTimeouts() Get the current setting of the retryPackedTimeouts property.
int	getSocketBufferSize() Use this method to retrieve the socket send and receive buffer size used when creating sockets.
boolean	getTimeStamps() Get the current setting of the timeStamps property.
int	getTrapQueueCapacity() Use this method to retrieve the trap queue capacity.
int	getTrapQueueExpansion() Use this method to retrieve the trap queue expansion increment.
void	setBufferDelay(int iDelay) BufferDelay affects response latency and network utilization.
void	setCacheExpireFactor(int iFactor) The CacheExpireFactor affects memory usage and future cache hit ratio.
void	setCacheExpireFloor(int iFloor) The CacheExpireFloor affects memory usage and future cache hit ratio.
void	setCachePrunePeriod(int iSecs) Sets the period of the cache Pruning task.
void	setClerkThreadPool(int iThreads) Sets the maximum number of concurrent Clerks.
void	setRetryPackedTimeouts(boolean bEnable) Enables/disables an automatic retry when a packed (multiple varbind) PDU times out.
void	setSocketBufferSize(int iSize) SocketBufferSize affects the size of SNMP packets that can be sent and received.
void	setTimeStamps(boolean bEnable) Enables/disables the automatic retrieval of timestamps with every get/get-next PDU sent to agents.
void	setTrapQueueCapacity(int iCapacity) The TrapQueueCapacity affects memory usage and trap reception.
void	setTrapQueueExpansion(int iExpansion) The TrapQueueExpansion affects memory usage and trap reception.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setSocketBufferSize

public void setSocketBufferSize(int iSize)

SocketBufferSize affects the size of SNMP packets that can be sent and received. The SO_RCVBUF and SO_SNDBUF options of any newly created socket are set to 'iSize'. The SO_RCVBUF and SO_SNDBUF options are used by the platform's networking code as a hint for the size to set the underlying network I/O buffers. These options set the maximum size of a packet that may be sent and received. Note: may also be set with System.Property "jsnmp.socketBufferSize"

Parameters:

iSize - the SocketBufferSize measured in bytes; if 0 then the send and receive buffer sizes of a socket will not be altered when it is created; default is 0

getSocketBufferSize

public int getSocketBufferSize()

Use this method to retrieve the socket send and receive buffer size used when creating sockets.

Returns:

the current SocketBufferSize in bytes; if 0 then the send and receive buffer sizes of a socket will not be altered when it is created

setBufferDelay

public void setBufferDelay(int iDelay)

BufferDelay affects response latency and network utilization. BufferDelay is the amount of time the jSNMP Service will wait to query an agent once it has received the first request targeted for that agent. This buffering results allows multiple requests of the same target agent to be packed into the same PDU. The primary benefit is reduced network load. The primary cost is latency of response. If the BufferDelay is set to zero, no packing will occur. For values greater than zero, the delay imposes a fixed latency for each group of requests. A group is defined by the number of requests made against an OID in an interval of length BufferDelay.

Note: may also be set with System.Property "jsnmp.bufferDelay"

Parameters:

iDelay - the BufferDelay measured in milliseconds, default is 20ms

getBufferDelay

public int getBufferDelay()

Use this method to retrieve the BufferDelay used to pack PDU's.

Returns:

the current BufferDelay in milliseconds

setClerkThreadPool

public void setClerkThreadPool(int iThreads)

Sets the maximum number of concurrent Clerks. The size of the ClerkThreadPool affects concurrency of order distribution and memory utilization. The delivery of orders is accomplished by a family of 'clerks.' Use this this method to set the maximum number of concurrent clerks. Larger numbers will improve concurrency of delivery which is useful for systems with high throughput or in the case of failed communications. Smaller numbers decrease memory usage. Note that this parameter must be set BEFORE the first order to the local SnmpService. Any change after the first order will have no effect. It may also be set with System.Property "jsnmp.clerkThreadPool".

Parameters:

iThreads - the number of concurrent clerks available for delivery of orders, default is 10

getClerkThreadPool

public int getClerkThreadPool()

Gets the current maximum number of concurrent clerks. Use this method to retrieve the maximum number of concurrent clerks available for delivering orders.

Returns:

the number of concurrent clerks available for delivery of orders

setTimeStamps

public void setTimeStamps(boolean bEnable)

Enables/disables the automatic retrieval of timestamps with every get/get-next PDU sent to agents. Enabling this property adds an 'extra' sysUpTime.0 request to every get/get-next PDU, and returns retrieved timestamp (converted to seconds) as part of the response SnmpVarBind sent to SnmpCustomers. This option may be overridden by retryPackedTimeouts. It may also be set with System.Property "jsnmp.retrieveTimeStamps".

Parameters:

bEnable - - true enables time stamp retrieval, false disables it.

getTimeStamps

public boolean getTimeStamps()

Get the current setting of the timeStamps property.

Returns:

current setting of the timeStamps property

setRetryPackedTimeouts

public void setRetryPackedTimeouts(boolean bEnable)

Enables/disables an automatic retry when a packed (multiple varbind) PDU times out. Some agents may not respond to multiple varbind PDUs with errors resulting in a timeout. jSNMP will pack multiple varbinds into the same PDU where possible to improve performance. jSNMP will also pack the PDU when the timeStamps option is set (see above). If this option is enabled and a packed PDU times out, jSNMP will break up the packed PDU and retry with single varbind PDUs. This option has precedence over the retrieveTimeStamps option. This means that if an automatic retry based on this option is invoked, the retry will not retrieve the sysUpTime.0 OID. It may also be set with System.Property "jsnmp.retryPackedTimeouts".

Parameters:

bEnable - - true enables retry, false disables it.

getRetryPackedTimeouts

public boolean getRetryPackedTimeouts()

Get the current setting of the retryPackedTimeouts property.

Returns:

current setting of the retryPackedTimeouts property

setCachePrunePeriod

public void setCachePrunePeriod(int iSecs)

Sets the period of the cache Pruning task. The cache of retrieved OID values is periodically pruned of stale members. Use this this method to set the period of the Pruning task. The CachePrunePeriod affects memory usage and system load. It may also be set with System.Property "jsnmp.cachePrunePeriod".

Parameters:

iSecs - the period of the Pruning task measured in seconds, default is 30

getCachePrunePeriod

public int getCachePrunePeriod()

Use this method to retrieve the period of the cache Pruning task.

Returns:

the current period of the Pruning task in seconds

setCacheExpireFloor

public void setCacheExpireFloor(int iFloor)

The CacheExpireFloor affects memory usage and future cache hit ratio. When the Pruning task is run, each cached OID is examined for staleness. Staleness is defined in terms of the ratio of time interval since the last retrieved value versus the most recently requested cache delay for that cachable entity. If this time interval is less than 'floor', the cache element is not considered stale. It may also be set with System.Property "jsnmp.cacheExpireFloor".

Parameters:

iFloor - the Expire Floor of the Pruning task, default is 60

getCacheExpireFloor

public int getCacheExpireFloor()

Use this method to retrieve the Expire Floor of the cache Pruning task.

Returns:

the current cache Expire Floor

setCacheExpireFactor

public void setCacheExpireFactor(int iFactor)

The CacheExpireFactor affects memory usage and future cache hit ratio. When the Pruning task is run, each cached OID is examined for staleness. Staleness is defined in terms of the ratio of time interval since the last retrieved value versus the most recently requested cache delay for that cachable entity. If this time interval is greater than 'factor' times the last requested cache delay, the cache element is considered stale and will be pruned. It may also be set with System.Property "jsnmp.cacheExpireFactor".

Parameters:

iFactor - the Expire Factor of the Pruning task, default is 2

getCacheExpireFactor

public int getCacheExpireFactor()

Use this method to retrieve the Expire Factor of the cache Pruning task.

Returns:

the current cache Expire Factor

setTrapQueueCapacity

public void setTrapQueueCapacity(int iCapacity)

The TrapQueueCapacity affects memory usage and trap reception. Traps are queued by the receiver thread and dispatched by another thread from the queue. A small TrapQueueCapacity will cause traps to be lost until the queue size is self-stabilized using TrapQueueExpansion increments to a size where traps are not lost because the queue is full. A large TrapQueueCapacity is a waste of memory, as traps cannot be received and enqueued fast enough to sustain a large queue. It may also be set with System.Property "jsnmp.trapQueueCapacity".

Parameters:

iCapacity - the initial trap queue capacity, default is 1000, min is 100

getTrapQueueCapacity

public int getTrapQueueCapacity()

Use this method to retrieve the trap queue capacity.

Returns:

current trap queue capacity

setTrapQueueExpansion

public void setTrapQueueExpansion(int iExpansion)

The TrapQueueExpansion affects memory usage and trap reception. Traps are queued by the receiver thread and dispatched by another thread from the queue. TrapQueueExpansion is used to increase for the trap queue size when a new trap is enqueued into a full trap queue. TrapQueueExpansion should be less than or equal to TrapQueueCapacity, though this is not enforced. A small TrapQueueExpansion will cause traps to be lost until the queue size is self-stabilized using TrapQueueExpansion increments to a size where traps are not lost because the queue is full. A large TrapQueueExpansion is a waste of memory, as traps cannot be received and enqueued fast enough to sustain a large queue. It may also be set with System.Property "jsnmp.trapQueueExpansion".

Parameters:

iExpansion - the initial trap queue expansion increment, default is 500, min is 10

getTrapQueueExpansion

public int getTrapQueueExpansion()

Use this method to retrieve the trap queue expansion increment.

Returns:

current trap queue expansion increment

getDumpPackets

public static boolean getDumpPackets()

Get the current setting of the dumpPackets property.

Returns:

current setting of the dumpPackets property

getCacheDisable

public static boolean getCacheDisable()

Get the current setting of the cacheDisable property.

Returns:

current setting of the cacheDisable property

getLoadRFC1213MIB

public static boolean getLoadRFC1213MIB()

Get the current setting of the loadRFC1213MIB property.

Returns:

true if load the RFC1213 MIB