Module org.snmp4j
Package org.snmp4j

Class PDU

  • All Implemented Interfaces:
    java.io.Serializable, BERSerializable
    Direct Known Subclasses:
    PDUv1, ScopedPDU

    public class PDU
    extends java.lang.Object
    implements BERSerializable, java.io.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:
    PDUv1, ScopedPDU, Serialized Form
    • Field Summary

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

      • GETNEXT

        public static final int GETNEXT
        Denotes a getnext (search) 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
      • 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 java.util.ArrayList<VariableBinding> variableBindings
      • errorStatus

        protected Integer32 errorStatus
      • type

        protected int type
    • Constructor Detail

      • 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,
                   java.util.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 Detail

      • 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​(java.util.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.
      • 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 java.util.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 &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 java.util.List<? extends VariableBinding> getVariableBindings()
        Gets the variable binding vector.
        Returns:
        the internal List containing the PDU's variable bindings.
      • setVariableBindings

        public void setVariableBindings​(java.util.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 java.lang.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 java.lang.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 java.io.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:
        java.io.IOException - if the stream could not be decoded by using BER rules.
      • decodeVariableBindings

        public static java.util.ArrayList<VariableBinding> decodeVariableBindings​(BERInputStream inputStream)
                                                                           throws java.io.IOException
        Throws:
        java.io.IOException
      • getBERLength

        public static int getBERLength​(java.util.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​(java.io.OutputStream outputStream)
                       throws java.io.IOException
        Description copied from interface: BERSerializable
        Encodes a Variable to an OutputStream.
        Specified by:
        encodeBER in interface BERSerializable
        Parameters:
        outputStream - an OutputStream.
        Throws:
        java.io.IOException - if an error occurs while writing to the stream.
      • encodeVariableBindings

        public static void encodeVariableBindings​(java.io.OutputStream outputStream,
                                                  java.util.List<VariableBinding> variableBindings)
                                           throws java.io.IOException
        Throws:
        java.io.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 java.lang.Object clone()
        Overrides:
        clone in class java.lang.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 java.lang.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​(java.lang.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 java.lang.String toString()
        Returns a string representation of the object.
        Overrides:
        toString in class java.lang.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 java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object