Module org.snmp4j
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:
3.0
Author:
Frank Fock
See Also:

  • Field Details

    • GET

      public static final int GET
      Denotes a get PDU.
      See Also:

    • GETNEXT

      public static final int GETNEXT
      Denotes a getnext (search) PDU.
      See Also:

    • RESPONSE

      public static final int RESPONSE
      Denotes a response PDU.
      See Also:

    • SET

      public static final int SET
      Denotes a set PDU.
      See Also:

    • 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:

    • GETBULK

      public static final int GETBULK
      Denotes a SNMPv2c/v3 getbulk PDU.
      See Also:

    • INFORM

      public static final int INFORM
      Denotes a SNMPv2c/v3 inform PDU (unprecisely also known as a confirmed notification).
      See Also:

    • TRAP

      public static final int TRAP
      Denotes a SNMPv2c/v3 notification PDU (undistinguishable from #TRAP).
      See Also:

    • NOTIFICATION

      public static final int NOTIFICATION
      Denotes a SNMPv2c/v3 notification PDU (undistinguishable from #NOTIFICATION).
      See Also:

    • REPORT

      public static final int REPORT
      Denotes a SNMPv3 report PDU.
      See Also:

    • noError

      public static final int noError
      Operation success (no error).
      See Also:

    • tooBig

      public static final int tooBig
      PDU encoding is too big for the transport used.
      See Also:

    • noSuchName

      public static final int noSuchName
      No such variable binding name, see error index.
      See Also:

    • badValue

      public static final int badValue
      Bad value in variable binding, see error index.
      See Also:

    • readOnly

      public static final int readOnly
      The variable binding is read-only, see error index.
      See Also:

    • genErr

      public static final int genErr
      An unspecific error caused by a variable binding, see error index.
      See Also:

    • noAccess

      public static final int noAccess
      The variable binding is not accessible by the current MIB view, see error index.
      See Also:

    • wrongType

      public static final int wrongType
      The variable binding's value has the wrong type, see error index.
      See Also:

    • wrongLength

      public static final int wrongLength
      The variable binding's value has the wrong length, see error index.
      See Also:

    • 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:

    • wrongEncoding

      public static final int wrongEncoding
      The variable binding's value has the wrong encoding, see error index.
      See Also:

    • noCreation

      public static final int noCreation
      The specified object does not exists and cannot be created, see error index.
      See Also:

    • 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:

    • resourceUnavailable

      public static final int resourceUnavailable
      The resource needed to assign a variable binding's value is presently unavailable, see error index.
      See Also:

    • commitFailed

      public static final int commitFailed
      Unable to commit a value, see error index.
      See Also:

    • undoFailed

      public static final int undoFailed
      Unable to undo a committed value, see error index.
      See Also:

    • authorizationError

      public static final int authorizationError
      Unauthorized access, see error index.
      See Also:

    • notWritable

      public static final int notWritable
      The variable's value cannot be modified, see error index.
      See Also:

    • inconsistentName

      public static final int inconsistentName
      The specified object does not exists and presently it cannot be created, see error index.
      See Also:

    • variableBindings

      protected ArrayList<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 &lt;= index &lt; {@link #size()})
      Returns:
      a VariableBinding instance. If index is out of bounds an exception is thrown.

    • get

      public List<VariableBinding> get(String... objectIdentifierOrName)
      Gets all the VariableBindings from this PDU whose object identifier (OID) equals or has the same prefix than the specified object identifier or name.
      Parameters:
      objectIdentifierOrName - a dotted numbered OID string like "1.3.6.1.4.1.4976" or an object name parsable by format as set by SNMP4JSettings.setOIDTextFormat(OIDTextFormat). If such a OID format is not set before this method is called, or if the objectIdentifierOrName could not be parsed/does not comply to the format rules, then a RuntimeException will be thrown.
      Returns:
      a list of VariableBindings whose OID is a parent of the object identifier(s) given as argument. The list is ordered by the given prefix OIDs and within the matches of each prefix OID, the list is ordered by occurrence in this PDU.
      Since:
      3.5.0

    • 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. If null, then all variable bindings will be returned.
      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 &lt;= index &lt; 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 List<? extends VariableBinding> getVariableBindings()
      Gets the variable binding vector.
      Returns:
      the internal List 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:

    • getErrorStatus

      public int getErrorStatus()
      Gets the error status of the PDU.
      Returns:
      a SNMP error status.
      See Also:

    • 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.

    • decodeVariableBindings

      public static ArrayList<VariableBinding> decodeVariableBindings(BERInputStream inputStream) throws IOException
      Throws:
      IOException

    • 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.

    • encodeVariableBindings

      public static void encodeVariableBindings(OutputStream outputStream, List<VariableBinding> variableBindings) throws IOException
      Throws:
      IOException

    • 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

    • getAll

      public List<VariableBinding> getAll()
      Gets all the VariableBindings of this PDU.
      Returns:
      a possibly empty list of VariableBinding instances.
      Since:
      3.5.0