Package org.snmp4j

Class PDU

java.lang.Object

org.snmp4j.PDU

All Implemented Interfaces:

Serializable, BERSerializable

Direct Known Subclasses:

PDUv1, ScopedPDU

public class PDU
extends Object
implements BERSerializable, Serializable

The PDU class represents a SNMP protocol data unit. The PDU version supported by the BER decoding and encoding methods of this class is v2.

The default PDU type is GET.

Version:

2.0

Author:

Frank Fock

See Also:

• PDUv1
• ScopedPDU
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final int	authorizationError	Unauthorized access, see error index.
static final int	badValue	Bad value in variable binding, see error index.
static final int	commitFailed	Unable to commit a value, see error index.
protected Integer32	errorIndex
protected Integer32	errorStatus
static final int	genErr	An unspecific error caused by a variable binding, see error index.
static final int	GET	Denotes a get PDU.
static final int	GETBULK	Denotes a SNMPv2c/v3 getbulk PDU.
static final int	GETNEXT	Denotes a getnext (search) PDU.
static final int	inconsistentName	The specified object does not exists and presently it cannot be created, see error index.
static final int	inconsistentValue	The variable binding's value is presently inconsistent with the current state of the target object, see error index.
static final int	INFORM	Denotes a SNMPv2c/v3 inform PDU (unprecisely also known as a confirmed notification).
static final int	noAccess	The variable binding is not accessible by the current MIB view, see error index.
static final int	noCreation	The specified object does not exists and cannot be created, see error index.
static final int	noError	Operation success (no error).
static final int	noSuchName	No such variable binding name, see error index.
static final int	NOTIFICATION	Denotes a SNMPv2c/v3 notification PDU (undistinguishable from #NOTIFICATION).
static final int	notWritable	The variable's value cannot be modified, see error index.
static final int	readOnly	The variable binding is read-only, see error index.
static final int	REPORT	Denotes a SNMPv3 report PDU.
protected Integer32	requestID
static final int	resourceUnavailable	The resource needed to assign a variable binding's value is presently unavailable, see error index.
static final int	RESPONSE	Denotes a response PDU.
static final int	SET	Denotes a set PDU.
static final int	tooBig	PDU encoding is too big for the transport used.
static final int	TRAP	Denotes a SNMPv2c/v3 notification PDU (undistinguishable from #TRAP).
protected int	type
static final int	undoFailed	Unable to undo a committed value, see error index.
static final int	V1TRAP	Denotes a SNMPv1 trap PDU.
protected Vector<VariableBinding>	variableBindings
static final int	wrongEncoding	The variable binding's value has the wrong encoding, see error index.
static final int	wrongLength	The variable binding's value has the wrong length, see error index.
static final int	wrongType	The variable binding's value has the wrong type, see error index.
static final int	wrongValue	The variable binding's value has a value that could under no circumstances be assigned, see error index.

Constructor Summary

Constructors

Constructor	Description
PDU()	Default constructor.
PDU(int pduType, List<? extends VariableBinding> vbs)	Constructs a new PDU from a type and a list of VariableBinding instances.
PDU(PDU other)	Copy constructor which creates a deep copy (clone) of the other PDU.

Method Summary

Modifier and Type	Method	Description
void	add(VariableBinding vb)	Adds a variable binding to this PDU.
void	addAll(List<? extends VariableBinding> vbs)	Adds a list of variable bindings to this PDU (see add(VariableBinding vb)).
void	addAll(VariableBinding[] vbs)	Adds an array of variable bindings to this PDU (see add(VariableBinding vb)).
void	addAllOIDs(VariableBinding[] vbs)	Adds new VariableBindings each with the OID of the corresponding variable binding of the supplied array to this PDU (see addOID(VariableBinding vb)).
void	addOID(VariableBinding vb)	Adds a new variable binding to this PDU by using the OID of the supplied VariableBinding.
void	clear()	Removes all variable bindings from the PDU and sets the request ID to zero.
Object	clone()
void	decodeBER(BERInputStream inputStream)	Decodes a Variable from an InputStream.
void	encodeBER(OutputStream outputStream)	Encodes a Variable to an OutputStream.
boolean	equals(Object obj)
VariableBinding	get(int index)	Gets the variable binding at the specified position.
int	getBERLength()	Returns the length of this BERSerializable object in bytes when encoded according to the Basic Encoding Rules (BER).
static int	getBERLength(List<? extends VariableBinding> variableBindings)	Computes the length in bytes of the BER encoded variable bindings without including the length of BER sequence length.
int	getBERPayloadLength()	Returns the length of the payload of this BERSerializable object in bytes when encoded according to the Basic Encoding Rules (BER).
protected int	getBERPayloadLengthPDU()
List<VariableBinding>	getBindingList(OID prefix)	Gets a list of VariableBindings whose OID prefix matches the supplied prefix.
int	getErrorIndex()	Gets the error index.
int	getErrorStatus()	Gets the error status of the PDU.
String	getErrorStatusText()	Gets a textual description of the error status.
int	getMaxRepetitions()	Gets the maximum repetitions of repeatable variable bindings in GETBULK requests.
int	getNonRepeaters()	Gets the number of non repeater variable bindings in a GETBULK PDU.
Integer32	getRequestID()	Gets the request ID associated with this PDU.
int	getType()	Gets the PDU type.
static int	getTypeFromString(String type)	Gets the PDU type identifier for a string representation of the type.
static String	getTypeString(int type)	Gets a string representation of the supplied PDU type.
Variable	getVariable(OID prefix)	Gets the first variable whose OID starts with the specified OID.
Vector<? extends VariableBinding>	getVariableBindings()	Gets the variable binding vector.
int	hashCode()
boolean	isConfirmedPdu()	Checks whether this PDU is a confirmed class PDU.
boolean	isResponsePdu()	Checks whether this PDU is a RESPONSE or [@link PDU#REPORT}.
void	remove(int index)	Removes the variable binding at the supplied position.
VariableBinding	set(int index, VariableBinding vb)	Sets the variable binding at the specified position.
void	setErrorIndex(int errorIndex)	Sets the error index.
void	setErrorStatus(int errorStatus)	Sets the error status of the PDU.
void	setMaxRepetitions(int maxRepetitions)	Sets the maximum repetitions of repeatable variable bindings in GETBULK requests.
void	setNonRepeaters(int nonRepeaters)	Sets the number of non repeater variable bindings in a GETBULK PDU.
void	setRequestID(Integer32 requestID)	Sets the request ID for this PDU.
void	setType(int type)	Sets the PDU type.
void	setVariableBindings(List<? extends VariableBinding> vbs)	Sets the VariableBindings for this PDU.
int	size()	Gets the number of variable bindings in the PDU.
VariableBinding[]	toArray()	Returns an array with the variable bindings of this PDU.
static String	toErrorStatusText(int errorStatus)	Returns textual description for the supplied error status value.
String	toString()	Returns a string representation of the object.
void	trim()	Remove the last variable binding from the PDU, if such an element exists.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

GET

public static final int GET

Denotes a get PDU.

See Also:

• Constant Field Values

GETNEXT

public static final int GETNEXT

Denotes a getnext (search) PDU.

See Also:

• Constant Field Values

RESPONSE

public static final int RESPONSE

Denotes a response PDU.

See Also:

• Constant Field Values

SET

public static final int SET

Denotes a set PDU.

See Also:

• Constant Field Values

V1TRAP

public static final int V1TRAP

Denotes a SNMPv1 trap PDU. This type can only be used with instances of the PDUv1 class.

See Also:

• Constant Field Values

GETBULK

public static final int GETBULK

Denotes a SNMPv2c/v3 getbulk PDU.

See Also:

• Constant Field Values

INFORM

public static final int INFORM

Denotes a SNMPv2c/v3 inform PDU (unprecisely also known as a confirmed notification).

See Also:

• Constant Field Values

TRAP

public static final int TRAP

Denotes a SNMPv2c/v3 notification PDU (undistinguishable from #TRAP).

See Also:

• Constant Field Values

NOTIFICATION

public static final int NOTIFICATION

Denotes a SNMPv2c/v3 notification PDU (undistinguishable from #NOTIFICATION).

See Also:

• Constant Field Values

REPORT

public static final int REPORT

Denotes a SNMPv3 report PDU.

See Also:

• Constant Field Values

noError

public static final int noError

Operation success (no error).

See Also:

• Constant Field Values

tooBig

public static final int tooBig

PDU encoding is too big for the transport used.

See Also:

• Constant Field Values

noSuchName

public static final int noSuchName

No such variable binding name, see error index.

See Also:

• Constant Field Values

badValue

public static final int badValue

Bad value in variable binding, see error index.

See Also:

• Constant Field Values

readOnly

public static final int readOnly

The variable binding is read-only, see error index.

See Also:

• Constant Field Values

genErr

public static final int genErr

An unspecific error caused by a variable binding, see error index.

See Also:

• Constant Field Values

noAccess

public static final int noAccess

The variable binding is not accessible by the current MIB view, see error index.

See Also:

• Constant Field Values

wrongType

public static final int wrongType

The variable binding's value has the wrong type, see error index.

See Also:

• Constant Field Values

wrongLength

public static final int wrongLength

The variable binding's value has the wrong length, see error index.

See Also:

• Constant Field Values

wrongValue

public static final int wrongValue

The variable binding's value has a value that could under no circumstances be assigned, see error index.

See Also:

• Constant Field Values

wrongEncoding

public static final int wrongEncoding

The variable binding's value has the wrong encoding, see error index.

See Also:

• Constant Field Values

noCreation

public static final int noCreation

The specified object does not exists and cannot be created, see error index.

See Also:

• Constant Field Values

inconsistentValue

public static final int inconsistentValue

The variable binding's value is presently inconsistent with the current state of the target object, see error index.

See Also:

• Constant Field Values

resourceUnavailable

public static final int resourceUnavailable

The resource needed to assign a variable binding's value is presently unavailable, see error index.

See Also:

• Constant Field Values

commitFailed

public static final int commitFailed

Unable to commit a value, see error index.

See Also:

• Constant Field Values

undoFailed

public static final int undoFailed

Unable to undo a committed value, see error index.

See Also:

• Constant Field Values

authorizationError

public static final int authorizationError

Unauthorized access, see error index.

See Also:

• Constant Field Values

notWritable

public static final int notWritable

The variable's value cannot be modified, see error index.

See Also:

• Constant Field Values

inconsistentName

public static final int inconsistentName

The specified object does not exists and presently it cannot be created, see error index.

See Also:

• Constant Field Values

variableBindings

protected Vector<VariableBinding> variableBindings

errorStatus

protected Integer32 errorStatus

errorIndex

protected Integer32 errorIndex

requestID

protected Integer32 requestID

type

protected int type

Constructor Details

PDU

public PDU()

Default constructor.

PDU

public PDU(PDU other)

Copy constructor which creates a deep copy (clone) of the other PDU.

Parameters:

other - the PDU to copy from.

PDU

public PDU(int pduType,
 List<? extends VariableBinding> vbs)

Constructs a new PDU from a type and a list of VariableBinding instances. The list will not be referenced, instead a deep copy of the variable bindings is executed (each variable binding will be cloned).

Parameters:

pduType - the PDU type.

vbs - the variable bindings.

Since:

2.2.4

Method Details

add

public void add(VariableBinding vb)

Adds a variable binding to this PDU. A NullPointerException is thrown if VariableBinding or its Variable is null.

Parameters:

vb - a VariableBinding instance.

addOID

public void addOID(VariableBinding vb)

Adds a new variable binding to this PDU by using the OID of the supplied VariableBinding. The value portion is thus set to null. This method should be used for GET type requests. For SET, TRAP and INFORM requests, the add(org.snmp4j.smi.VariableBinding) method should be used instead.

Parameters:

vb - a VariableBinding instance.

Since:

1.8

addAll

public void addAll(VariableBinding[] vbs)

Adds an array of variable bindings to this PDU (see add(VariableBinding vb)).

Parameters:

vbs - an array of VariableBinding instances. The instances in the array will be appended to the current list of variable bindings in the PDU.

addAll

public void addAll(List<? extends VariableBinding> vbs)

Adds a list of variable bindings to this PDU (see add(VariableBinding vb)).

Parameters:

vbs - a list of VariableBinding instances. The instances in the list will be appended to the current list of variable bindings in the PDU.

Since:

2.2.4

addAllOIDs

public void addAllOIDs(VariableBinding[] vbs)

Adds new VariableBindings each with the OID of the corresponding variable binding of the supplied array to this PDU (see addOID(VariableBinding vb)).

Parameters:

vbs - an array of VariableBinding instances. For each instance in the supplied array, a new VariableBinding created by new VariableBinding(OID) will be appended to the current list of variable bindings in the PDU.

Since:

1.8

get

public VariableBinding get(int index)

Gets the variable binding at the specified position.

Parameters:

index - a zero based positive integer (0 <= index < {@link #size()})

Returns:

a VariableBinding instance. If index is out of bounds an exception is thrown.

getVariable

public Variable getVariable(OID prefix)

Gets the first variable whose OID starts with the specified OID.

Parameters:

prefix - the search OID.

Returns:

the Variable of the first VariableBinding whose prefix matches oid. If no such element could be found, null is returned.

Since:

2.0

getBindingList

public List<VariableBinding> getBindingList(OID prefix)

Gets a list of VariableBindings whose OID prefix matches the supplied prefix.

Parameters:

prefix - the search OID.

Returns:

a List of all VariableBindings whose prefix matches oid. If no such element could be found, an empty List is returned.

set

public VariableBinding set(int index,
 VariableBinding vb)

Sets the variable binding at the specified position.

Parameters:

index - a zero based positive integer (0 <= index < size()) If index is out of bounds an exception is thrown.

vb - a VariableBinding instance (null is not allowed).

Returns:

the variable binding that has been replaced.

remove

public void remove(int index)

Removes the variable binding at the supplied position.

Parameters:

index - a position >= 0 and < size().

size

public int size()

Gets the number of variable bindings in the PDU.

Returns:

the size of the PDU.

getVariableBindings

public Vector<? extends VariableBinding> getVariableBindings()

Gets the variable binding vector.

Returns:

the internal Vector containing the PDU's variable bindings.

setVariableBindings

public void setVariableBindings(List<? extends VariableBinding> vbs)

Sets the VariableBindings for this PDU.

Parameters:

vbs - a list of VariableBinding instances which must not be null.

Since:

2.1

trim

public void trim()

Remove the last variable binding from the PDU, if such an element exists.

setErrorStatus

public void setErrorStatus(int errorStatus)

Sets the error status of the PDU.

Parameters:

errorStatus - a SNMP error status.

See Also:

• SnmpConstants

getErrorStatus

public int getErrorStatus()

Gets the error status of the PDU.

Returns:

a SNMP error status.

See Also:

• SnmpConstants

getErrorStatusText

public String getErrorStatusText()

Gets a textual description of the error status.

Returns:

a String containing an element of the SnmpConstants.SNMP_ERROR_MESSAGES array for a valid error status. "Unknown error: <errorStatusNumber>" is returned for any other value.

toErrorStatusText

public static String toErrorStatusText(int errorStatus)

Returns textual description for the supplied error status value.

Parameters:

errorStatus - an error status.

Returns:

a String containing an element of the SnmpConstants.SNMP_ERROR_MESSAGES array for a valid error status. "Unknown error: <errorStatusNumber>" is returned for any other value.

Since:

1.7

setErrorIndex

public void setErrorIndex(int errorIndex)

Sets the error index.

Parameters:

errorIndex - an integer value >= 0 where 1 denotes the first variable binding.

getErrorIndex

public int getErrorIndex()

Gets the error index.

Returns:

an integer value >= 0 where 1 denotes the first variable binding.

isConfirmedPdu

public boolean isConfirmedPdu()

Checks whether this PDU is a confirmed class PDU.

Returns:

boolean

isResponsePdu

public boolean isResponsePdu()

Checks whether this PDU is a RESPONSE or [@link PDU#REPORT}.

Returns:

true if getType() returns RESPONSE or [@link PDU#REPORT} and false otherwise.

Since:

2.4.1

getBERLength

public int getBERLength()

Description copied from interface: BERSerializable

Returns the length of this BERSerializable object in bytes when encoded according to the Basic Encoding Rules (BER).

Specified by:

getBERLength in interface BERSerializable

Returns:

the BER encoded length of this variable.

getBERPayloadLength

public int getBERPayloadLength()

Description copied from interface: BERSerializable

Returns the length of the payload of this BERSerializable object in bytes when encoded according to the Basic Encoding Rules (BER).

Specified by:

getBERPayloadLength in interface BERSerializable

Returns:

the BER encoded length of this variable.

decodeBER

public void decodeBER(BERInputStream inputStream)
               throws IOException

Description copied from interface: BERSerializable

Decodes a Variable from an InputStream.

Specified by:

decodeBER in interface BERSerializable

Parameters:

inputStream - an InputStream containing a BER encoded byte stream.

Throws:

IOException - if the stream could not be decoded by using BER rules.

getBERLength

public static int getBERLength(List<? extends VariableBinding> variableBindings)

Computes the length in bytes of the BER encoded variable bindings without including the length of BER sequence length.

Parameters:

variableBindings - a list of variable bindings.

Returns:

the length in bytes of the BER encoded VB list.

getBERPayloadLengthPDU

protected int getBERPayloadLengthPDU()

encodeBER

public void encodeBER(OutputStream outputStream)
               throws IOException

Description copied from interface: BERSerializable

Encodes a Variable to an OutputStream.

Specified by:

encodeBER in interface BERSerializable

Parameters:

outputStream - an OutputStream.

Throws:

IOException - if an error occurs while writing to the stream.

clear

public void clear()

Removes all variable bindings from the PDU and sets the request ID to zero. This can be used to reuse a PDU for another request.

setType

public void setType(int type)

Sets the PDU type.

Parameters:

type - the type of the PDU (e.g. GETNEXT, SET, etc.)

getType

public int getType()

Gets the PDU type. The default is GETNEXT.

Returns:

the PDU's type.

clone

public Object clone()

Overrides:

clone in class Object

getRequestID

public Integer32 getRequestID()

Gets the request ID associated with this PDU.

Returns:

an Integer32 instance.

setRequestID

public void setRequestID(Integer32 requestID)

Sets the request ID for this PDU. When the request ID is not set or set to zero, the message processing model will generate a unique request ID for the PDU when sent.

Parameters:

requestID - a unique request ID.

getTypeString

public static String getTypeString(int type)

Gets a string representation of the supplied PDU type.

Parameters:

type - a PDU type.

Returns:

a string representation of type, for example "GET".

getTypeFromString

public static int getTypeFromString(String type)

Gets the PDU type identifier for a string representation of the type.

Parameters:

type - the string representation of a PDU type: GET, GETNEXT, GETBULK, SET, INFORM, RESPONSE, REPORT, TRAP, V1TRAP).

Returns:

the corresponding PDU type constant, or Integer.MIN_VALUE of the supplied type is unknown.

toString

public String toString()

Returns a string representation of the object.

Overrides:

toString in class Object

Returns:

a string representation of the object.

getMaxRepetitions

public int getMaxRepetitions()

Gets the maximum repetitions of repeatable variable bindings in GETBULK requests.

Returns:

an integer value >= 0.

setMaxRepetitions

public void setMaxRepetitions(int maxRepetitions)

Sets the maximum repetitions of repeatable variable bindings in GETBULK requests.

Parameters:

maxRepetitions - an integer value >= 0.

getNonRepeaters

public int getNonRepeaters()

Gets the number of non repeater variable bindings in a GETBULK PDU.

Returns:

an integer value >= 0 and <= size()

setNonRepeaters

public void setNonRepeaters(int nonRepeaters)

Sets the number of non repeater variable bindings in a GETBULK PDU.

Parameters:

nonRepeaters - an integer value >= 0 and <= size()

toArray

public VariableBinding[] toArray()

Returns an array with the variable bindings of this PDU.

Returns:

an array of VariableBinding instances of this PDU in the same order as in the PDU.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object