com.sun.management.snmp.agent
Class SnmpProxy

java.lang.Object
  com.sun.management.snmp.agent.SnmpMibAgent
      com.sun.management.snmp.agent.SnmpProxy

All Implemented Interfaces:

SnmpMibAgentMBean, Serializable, MBeanRegistration

Direct Known Subclasses:

SnmpV3Proxy

public class SnmpProxy
extends SnmpMibAgent
implements Serializable

The SnmpProxy class provides an implementation of an SNMP proxy. It is a MBean forwarding calls to a remote sub agent. Multiple instances of SnmpProxy can run within an agent. Each of them being a proxy for a remote agent.

SnmpProxy implements the whole set of SNMP operations :

• get
• set
• getNext
• getBulk

SnmpProxy fully translates SNMP V1 to SNMP V2 and SNMP V2 to SNMP V1. It allows also V1 to V1 and V2 to V2 forwarding. SnmpProxy doesn't deal with traps.

Handled manager protocols :

• SNMP V1
• SNMP V2
• SNMP V3

The V1 or V2 or V3 ==> V1 or V2 security parameters follow the rules coded in the method translateParameters. If you want to change them, just overloaded this method.

The policy details are:

• SNMP V1 or V2 received call : The received community strings are reused.
• SNMP V3 received call : If a context name is provided (means that the proxy has been registered in the scope of a context), public is used as the read community string and private as the write one.

Java DMK 5.0 introduces the notion of SNMP engine. An engine is generally associated to an SNMP entity. When embedding a proxy within a Java DMK agent, the SnmpV3AdaptorServer engine must be passed.

Since:

Java DMK 5.1

See Also:

Serialized Form

Field Summary

static long

defaultTimeout The default timeout is 10 seconds.

Fields inherited from class com.sun.management.snmp.agent.SnmpMibAgent

server

Constructor Summary

SnmpProxy(SnmpEngine engine, SnmpPeer peer, String rootOid)
Initializes this SNMP proxy with a SnmpPeer to which calls are forwarded.

SnmpProxy(SnmpEngine engine, SnmpPeer peer, String rootOid, String name)
Initializes this SNMP proxy with a SnmpPeer to which calls are forwarded.

Method Summary

void	check(SnmpMibRequest inRequest) Implement the check method from the abstract SnmpMibAgent class.
void	forwardSetRequestOnCheck(boolean check) By default, set requests are forwarded when set(SnmpMibRequest request) is called.
void	get(SnmpMibRequest inRequest) Implement the get method from the abstract SnmpMibAgent class.
protected void	get(SnmpPeer peer, SnmpSession session, SnmpMibRequest inRequest) The get implementation.
void	getBulk(SnmpMibRequest request, int nonRepeat, int maxRepeat) Implement the getBulk method from the abstract SnmpMibAgent class.
SnmpEngine	getEngine() Returns the SNMP engine the proxy is based on.
String	getMibName() Gets the distant agent MIB name.
void	getNext(SnmpMibRequest inRequest) Implement the getNext method from the abstract SnmpMibAgent class.
protected void	getNext(SnmpPeer peer, SnmpSession session, SnmpMibRequest inRequest) The getNext implementation.
SnmpPeer	getPeer() Returns the Peer associated with this proxy.
long[]	getRootOid() Returns the root object identifier of the MIB.
long	getTimeout() Gets the proxy / sub agent communication total timeout.
protected boolean	handleReport(SnmpRequest request) Called when a report is received when forwarding a request.
void	hideInvalidResponseError(boolean hide) Hides invalid response errors.
void	init() Initialization of the SnmpProxy with no registration in Java DMK.
boolean	isInvalidResponseErrorHidden() Checks if invalid response errors are hidden.
boolean	isSetRequestForwardedOnCheck() Returns the way a set request is forwarded by this SnmpProxy.
ObjectName	preRegister(MBeanServer server, ObjectName name) Initialization of the SnmpProxy with registration in Java DMK.
void	set(SnmpMibRequest inRequest) Implement the set method from the abstract SnmpMibAgent class.
protected void	set(SnmpPeer peer, SnmpSession session, SnmpMibRequest inRequest) The set implementation.
void	setTimeout(long t) Sets the proxy / agent communication total timeout.
boolean	skipError() True means that this proxy doesn't throw exception in the case of erroneous getnext.
void	skipError(boolean skip) If the proxied agent is answering an error during a getnext or getbulk, this proxy will throw a SnmpStatusException.
protected SnmpParams	translateParameters(SnmpMibRequest request) Return the parameters to use when sending the call.

Methods inherited from class com.sun.management.snmp.agent.SnmpMibAgent

getBindingState, getMBeanServer, getSnmpAdaptor, getSnmpAdaptorName, newMibRequest, newMibRequest, postDeregister, postRegister, preDeregister, setSnmpAdaptor, setSnmpAdaptor, setSnmpAdaptor, setSnmpAdaptor, setSnmpAdaptorName, setSnmpAdaptorName, setSnmpAdaptorName, setSnmpAdaptorName

Methods inherited from class java.lang.Object

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

Field Detail

defaultTimeout

public static final long defaultTimeout

The default timeout is 10 seconds.

See Also:

Constant Field Values

Constructor Detail

SnmpProxy

public SnmpProxy(SnmpEngine engine,
                 SnmpPeer peer,
                 String rootOid)
          throws SnmpStatusException,
                 IllegalArgumentException

Initializes this SNMP proxy with a SnmpPeer to which calls are forwarded. The passed root OID is used when registering the proxy within the adaptor. The proxy name default value is "SnmpProxy".

Parameters:

engine - The SNMP adaptor engine.

peer - The peer representing the proxied agent.

rootOid - The proxy root OID.

Throws:

IllegalArgumentException - if the passed engine is null.

SnmpStatusException - An error occurred while accessing a MIB node.

SnmpProxy

public SnmpProxy(SnmpEngine engine,
                 SnmpPeer peer,
                 String rootOid,
                 String name)
          throws SnmpStatusException,
                 IllegalArgumentException

Initializes this SNMP proxy with a SnmpPeer to which calls are forwarded. The passed root OID is used when registering the proxy within the adaptor. The name is used when registering the proxy in the SnmpAdaptorServer

Parameters:

engine - The SNMP adaptor engine.

peer - The peer representing the proxied agent.

rootOid - The proxy root OID.

name - The proxy name.

Throws:

IllegalArgumentException - if the passed engine is null.

SnmpStatusException - An error occurred while accessing a MIB node.

Method Detail

skipError

public void skipError(boolean skip)

If the proxied agent is answering an error during a getnext or getbulk, this proxy will throw a SnmpStatusException. In some cases (multiple proxy registered in the same adaptor), it can be useful to skip the error answer. To do so, you must call this method passing it true.

By default a proxy will not skip the error.

Parameters:

skip - True will skip, false will not.

skipError

public boolean skipError()

True means that this proxy doesn't throw exception in the case of erroneous getnext. False means that this proxy throws an exception.

Returns:

The skip error status.

getEngine

public SnmpEngine getEngine()

Returns the SNMP engine the proxy is based on.

Returns:

The SNMP engine used.

getTimeout

public long getTimeout()

Gets the proxy / sub agent communication total timeout.

Returns:

The timeout in milliseconds.

setTimeout

public void setTimeout(long t)

Sets the proxy / agent communication total timeout. This method is thread-safe. Any ongoing communication will be not affected by the setting. The default timeout is SnmpProxy.defaultTimeout.

Parameters:

t - The timeout in milliseconds.

init

public void init()
          throws IllegalAccessException

Initialization of the SnmpProxy with no registration in Java DMK.

Specified by:

init in class SnmpMibAgent

Throws:

IllegalAccessException - The used session cannot be initialized.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Initialization of the SnmpProxy with registration in Java DMK.

Specified by:

preRegister in interface MBeanRegistration

Specified by:

preRegister in class SnmpMibAgent

Parameters:

server - The reference to the MBean server.

name - The object name of this SnmpProxy.

Returns:

The name of the SNMP MIB registered.

Throws:

Exception

getMibName

public String getMibName()

Gets the distant agent MIB name.

Specified by:

getMibName in interface SnmpMibAgentMBean

Overrides:

getMibName in class SnmpMibAgent

Returns:

The distant agent MIB name.

get

public void get(SnmpMibRequest inRequest)
         throws SnmpStatusException

Implement the get method from the abstract SnmpMibAgent class. Handles V1 to V2 and V2 to V1 SNMP protocol translations.

Specified by:

get in interface SnmpMibAgentMBean

Overrides:

get in class SnmpMibAgent

Parameters:

inRequest - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

Throws:

SnmpStatusException - An error occurred during the operation.

See Also:

SnmpMibAgent.get(SnmpMibRequest)

set

public void set(SnmpMibRequest inRequest)
         throws SnmpStatusException

Implement the set method from the abstract SnmpMibAgent class. Handles V1 to V2 and V2 to V1 SNMP protocol translations.

Specified by:

set in interface SnmpMibAgentMBean

Overrides:

set in class SnmpMibAgent

Parameters:

inRequest - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

Throws:

SnmpStatusException - An error occurred during the operation.

See Also:

SnmpMibAgent.set(SnmpMibRequest)

forwardSetRequestOnCheck

public void forwardSetRequestOnCheck(boolean check)

By default, set requests are forwarded when set(SnmpMibRequest request) is called. Doing so makes the sub agent returned errors to be systematically mapped to undoFailed. If you want more details on the sub agent error status, call this method with true value. The set request will be then forwarded when check(SnmpMibRequest request) is called. No error translation will be done.

Parameters:

check - True, the set request is forwarded on check, false the set request is forwarded on set.

isSetRequestForwardedOnCheck

public boolean isSetRequestForwardedOnCheck()

Returns the way a set request is forwarded by this SnmpProxy.

Returns:

True, the set request is forwarded on check, false the set request is forwarded on set.

hideInvalidResponseError

public void hideInvalidResponseError(boolean hide)

Hides invalid response errors.

Sub agent invalid response requests (e.g. invalid BER encoding) can lead to a request timeout. This behavior can be changed by calling this method and passing it false. Providing false will make this SnmpProxy to throw a GenError if an internal error occurs.

Parameters:

hide - True, hide the internal errors, requests will fail in timeout. False throw a GenError.

isInvalidResponseErrorHidden

public boolean isInvalidResponseErrorHidden()

Checks if invalid response errors are hidden.

Invalid response requests (e.g. invalid BER encoding) are dropped by the manager API. This makes the requests to timeout. This behavior can be changed by calling the method hideInvalidResponseError. By default the errors are hidden.

Returns:

true, the internal errors are hidden (Requests failing in timeout). False, the internal errors are not hidden (GenError is thrown).

check

public void check(SnmpMibRequest inRequest)
           throws SnmpStatusException

Implement the check method from the abstract SnmpMibAgent class. By default nothing is done on check. If forwardSetRequestOnCheck has been set to true, the set request is forwarded on the check.

Doing the set on check allows you to debug easily your master agent. The sub agent returned errors are forwarded to the manager without any translation (undoFailed is the error status returned when the set is done on the set). Handles V1 to V2 and V2 to V1 SNMP protocol translations.

Specified by:

check in interface SnmpMibAgentMBean

Overrides:

check in class SnmpMibAgent

Parameters:

inRequest - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

Throws:

SnmpStatusException - An error occurred during the operation.

See Also:

SnmpMibAgent.check(SnmpMibRequest)

getNext

public void getNext(SnmpMibRequest inRequest)
             throws SnmpStatusException

Implement the getNext method from the abstract SnmpMibAgent class. Handles V1 to V2 and V2 to V1 SNMP protocol translations.

Specified by:

getNext in interface SnmpMibAgentMBean

Overrides:

getNext in class SnmpMibAgent

Parameters:

inRequest - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

Throws:

SnmpStatusException - An error occurred during the operation.

See Also:

SnmpMibAgent.getNext(SnmpMibRequest)

getBulk

public void getBulk(SnmpMibRequest request,
                    int nonRepeat,
                    int maxRepeat)
             throws SnmpStatusException

Implement the getBulk method from the abstract SnmpMibAgent class. Handles V1 to V2 and V2 to V1 SNMP protocol translations. You have to be aware that getBulk is implemented by issuing multiple getNext. You will receive as many getNext(com.sun.management.snmp.agent.SnmpMibRequest) as repetition is needed.

Specified by:

getBulk in interface SnmpMibAgentMBean

Overrides:

getBulk in class SnmpMibAgent

Parameters:

request - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

nonRepeat - The number of variables, starting with the first variable in the variable-bindings, for which a single lexicographic successor is requested.

maxRepeat - The number of lexicographic successors requested for each of the last R variables. R is the number of variables following the first nonRepeat variables for which multiple lexicographic successors are requested.

Throws:

SnmpStatusException - An error occurred during the operation.

See Also:

SnmpMibAgent.getBulk(SnmpMibRequest,int,int)

getRootOid

public long[] getRootOid()

Returns the root object identifier of the MIB.

Specified by:

getRootOid in class SnmpMibAgent

Returns:

The remote sub agent root OID.

getPeer

public final SnmpPeer getPeer()

Returns the Peer associated with this proxy.

Returns:

The peer modeling the distant host.

handleReport

protected boolean handleReport(SnmpRequest request)

Called when a report is received when forwarding a request. If the returned value is true, the proxy will retry the current request.

Parameters:

request - The request containing the received report.

Returns:

True means retry the call, the report has been handled. False means don't retry, the report wasn't fixed.

The default implementation does nothing and returns false.

translateParameters

protected SnmpParams translateParameters(SnmpMibRequest request)
                                  throws SnmpStatusException

Return the parameters to use when sending the call. The info contained in the SnmpMibRequest PDU are reused in order to construct new SnmpParams. The returned parameters are passed to the session default peer. Overload this method in order to change the default policy.

Parameters:

request - The received request.

Returns:

The parameters to use when forwarding the call.

Throws:

SnmpStatusException

get

protected void get(SnmpPeer peer,
                   SnmpSession session,
                   SnmpMibRequest inRequest)
            throws SnmpStatusException

The get implementation. Forward the call to the passed peer using the passed SnmpSession.

Be aware that session and peer parameters are SnmpProxy attributes. Modifying them leads to unpredictable behavior. This method should not be overridden.

Parameters:

peer - The SnmpPeer on which the call is forwarded

session - The session used to forward the call. If the proxy translates from SNMP V2 to SNMP V1, you must provide a fixed session.

inRequest - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

Throws:

SnmpStatusException - An error occurred during the operation.

getNext

protected void getNext(SnmpPeer peer,
                       SnmpSession session,
                       SnmpMibRequest inRequest)
                throws SnmpStatusException

The getNext implementation. Forward the call to the passed peer using the passed SnmpSession.

Be aware that session and peer parameters are SnmpProxy attributes. Modifying them leads to unpredictable behavior. This method should not be overridden.

Parameters:

peer - The SnmpPeer on which the call is forwarded

session - The session used to forward the call. If the proxy translates from SNMP V2 to SNMP V1, you must provide a fixed session.

inRequest - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

Throws:

SnmpStatusException - An error occurred during the operation.

set

protected void set(SnmpPeer peer,
                   SnmpSession session,
                   SnmpMibRequest inRequest)
            throws SnmpStatusException

The set implementation. Forward the call to the passed peer using the passed SnmpSession.

Be aware that session and peer parameters are SnmpProxy attributes. Modifying them leads to unpredictable behavior. This method should not be overridden.

Parameters:

peer - The SnmpPeer on which the call is forwarded

session - The session used to forward the call. If the proxy translates from SNMP V2 to SNMP V1, you must provide a fixed session.

inRequest - The SnmpMibRequest object holding the list of variable to be retrieved. This list is composed of SnmpVarBind objects.

Throws:

SnmpStatusException - An error occurred during the operation.