001: /*
002: * SNMP Package
003: *
004: * Copyright (C) 2004, Jonathan Sevy <jsevy@mcs.drexel.edu>
005: *
006: * This is free software. Redistribution and use in source and binary forms, with
007: * or without modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * 1. Redistributions of source code must retain the above copyright notice, this
011: * list of conditions and the following disclaimer.
012: * 2. Redistributions in binary form must reproduce the above copyright notice,
013: * this list of conditions and the following disclaimer in the documentation
014: * and/or other materials provided with the distribution.
015: * 3. The name of the author may not be used to endorse or promote products
016: * derived from this software without specific prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
019: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
021: * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
022: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
023: * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
024: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
025: * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
026: * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027: *
028: */
029:
030: package snmp;
031:
032: /**
033: * SNMPRequestListener is an interface that must be implemented by any class which wishes
034: * to act as a handler for request messages sent from remote SNMP management entities.
035: * The SNMPv1AgentInterface class listens for request messages, and passes any it receives on to
036: * SNMPRequestListener subclasses that have registered with it through its addRequestListener() method.
037: */
038:
039: public interface SNMPRequestListener {
040:
041: /**
042: * Handles Get- or Set- request messages. The supplied request PDU may contain multiple OIDs; this
043: * method should process those OIDs it understands, and return an SNMPVarBindList containing those OIDs
044: * which it has handled and their corresponding values. The order of returned OID-value pairs is not
045: * important, as the SNMPv1AgentInterface will order the information appropriately. Each implementer of
046: * SNMPRequestListener will likely handle only a subset of the list of supplied OIDs; those OIDs which
047: * are not relevant to a particular listener should be ignored, to be handled by another SNMPRequestListener.
048: * If any OIDs remain unhandled after all listeners' processRequest() methods have been called, the
049: * SNMPv1AgentInterface will return an appropriate error indication to the management entity.
050: *
051: * @throws SNMPGetException, SNMPSetException
052: * If a listener receives a request for an OID which it is intended to handle, but there is a problem with
053: * the request - e.g., a set-request for a value which is read-only, or an incorrect value type for a set - the
054: * listener should throw an SNMPGetException or SNMPSetException to indicate the error. The exception should
055: * include both the index of the OID in the list of supplied OIDs, as well as an error status code (status values
056: * are provided as constants in the SNMPRequestException class definition). The SNMPRequestException class and
057: * subclasses provide constructors allowing the specification of the error index and status code. Note that the
058: * error index follows the SNMP convention of starting at 1, not 0: thus if there is a problem with the first OID,
059: * the error index should be 1. The SNMPAgentInterface will use the information in the exception to communicate
060: * the error to the requesting management entity. The community name should also be used to determine if a request
061: * is valid for the supplied community name.
062: *
063: */
064:
065: public SNMPSequence processRequest(SNMPPDU requestPDU,
066: String communityName) throws SNMPGetException,
067: SNMPSetException;
068:
069: /**
070: * Handles Get-Next- request messages. The supplied request PDU may contain multiple OIDs; this
071: * method should process those OIDs it understands, and return an SNMPVarBindList containing special
072: * variable pairs indicating those supplied OIDs which it has handled, i.e., it must indicate a
073: * supplied OID, the "next" OID, and the value of this next OID. To do this, the return value is a
074: * sequence of SNMPVariablePairs, in which the first component - the OID - is one of the supplied OIDs,
075: * and the second component - the value - is itself an SNMPVariablePair containing the "next" OID and
076: * its value:
077: *
078: * return value = sequence of SNMPVariablePair(original OID, SNMPVariablePair(following OID, value))
079: *
080: * In this way the SNMPv1AgentInterface which calls this method will be able to determine which of the
081: * supplied OIDs each "next" OID corresponds to.
082: *
083: * The order of returned "double" OID-(OID-value) pairs is not important, as the SNMPv1AgentInterface
084: * will order the information appropriately in the response. Each implementer of
085: * SNMPRequestListener will likely handle only a subset of the list of supplied OIDs; those OIDs which
086: * are not relevant to a particular listener should be ignored, to be handled by another SNMPRequestListener.
087: * If any OIDs remain unhandled after all listeners' processRequest() methods have been called, the
088: * SNMPv1AgentInterface will return an appropriate error indication to the management entity.
089: *
090: * @throws SNMPGetException
091: * If a listener receives a request for an OID which it is intended to handle, but there is a problem with
092: * the request - e.g., a get-next request for a value which is not readable for the supplied community name -
093: * the listener should throw an SNMPGetException to indicate the error. The exception should
094: * include both the index of the OID in the list of supplied OIDs, as well as an error status code (status values
095: * are provided as constants in the SNMPRequestException class definition). The SNMPRequestException class and
096: * subclasses provide constructors allowing the specification of the error index and status code. Note that the
097: * error index follows the SNMP convention of starting at 1, not 0: thus if there is a problem with the first OID,
098: * the error index should be 1. The SNMPAgentInterface will use the information in the exception to communicate
099: * the error to the requesting management entity. The community name should also be used to determine if a request
100: * is valid for the supplied community name.
101: *
102: */
103:
104: public SNMPSequence processGetNextRequest(SNMPPDU requestPDU,
105: String communityName) throws SNMPGetException;
106:
107: }
|