001: /*
002: * Copyright 2000-2003 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.jmx.snmp.agent;
027:
028: import com.sun.jmx.snmp.SnmpPduPacket;
029: import com.sun.jmx.snmp.SnmpPdu;
030: import com.sun.jmx.snmp.SnmpStatusException;
031:
032: /**
033: * This interface is provided to enable fine customization of the SNMP
034: * agent behaviour.
035: *
036: * <p>You will not need to implement this interface except if your agent
037: * needs extra customization requiring some contextual information.</p>
038: *
039: * <p>If an SnmpUserDataFactory is set on the SnmpAdaptorServer, then a new
040: * object containing user-data will be allocated through this factory
041: * for each incoming request. This object will be passed along to
042: * the SnmpMibAgent within SnmpMibRequest objects. By default, no
043: * SnmpUserDataFactory is set on the SnmpAdaptorServer, and the contextual
044: * object passed to SnmpMibAgent is null.</p>
045: *
046: * <p>You can use this feature to obtain on contextual information
047: * (such as community string etc...) or to implement a caching
048: * mechanism, or for whatever purpose might be required by your specific
049: * agent implementation.</p>
050: *
051: * <p>The sequence <code>allocateUserData() / releaseUserData()</code> can
052: * also be used to implement a caching mechanism:
053: * <ul>
054: * <li><code>allocateUserData()</code> could be used to allocate
055: * some cache space,</li>
056: * <li>and <code>releaseUserData()</code> could be used to flush it.</li>
057: * </ul></p>
058: *
059: * <p><b>This API is a Sun Microsystems internal API and is subject
060: * to change without notice.</b></p>
061: * @see com.sun.jmx.snmp.agent.SnmpMibRequest
062: * @see com.sun.jmx.snmp.agent.SnmpMibAgent
063: * @see com.sun.jmx.snmp.daemon.SnmpAdaptorServer
064: *
065: **/
066: public interface SnmpUserDataFactory {
067: /**
068: * Called by the <CODE>SnmpAdaptorServer</CODE> adaptor.
069: * Allocate a contextual object containing some user data. This method
070: * is called once for each incoming SNMP request. The scope
071: * of this object will be the whole request. Since the request can be
072: * handled in several threads, the user should make sure that this
073: * object can be accessed in a thread-safe manner. The SNMP framework
074: * will never access this object directly - it will simply pass
075: * it to the <code>SnmpMibAgent</code> within
076: * <code>SnmpMibRequest</code> objects - from where it can be retrieved
077: * through the {@link com.sun.jmx.snmp.agent.SnmpMibRequest#getUserData() getUserData()} accessor.
078: * <code>null</code> is considered to be a valid return value.
079: *
080: * This method is called just after the SnmpPduPacket has been
081: * decoded.
082: *
083: * @param requestPdu The SnmpPduPacket received from the SNMP manager.
084: * <b>This parameter is owned by the SNMP framework and must be
085: * considered as transient.</b> If you wish to keep some of its
086: * content after this method returns (by storing it in the
087: * returned object for instance) you should clone that
088: * information.
089: *
090: * @return A newly allocated user-data contextual object, or
091: * <code>null</code>
092: * @exception SnmpStatusException If an SnmpStatusException is thrown,
093: * the request will be aborted.
094: *
095: * @since 1.5
096: **/
097: public Object allocateUserData(SnmpPdu requestPdu)
098: throws SnmpStatusException;
099:
100: /**
101: * Called by the <CODE>SnmpAdaptorServer</CODE> adaptor.
102: * Release a previously allocated contextual object containing user-data.
103: * This method is called just before the responsePdu is sent back to the
104: * manager. It gives the user a chance to alter the responsePdu packet
105: * before it is encoded, and to free any resources that might have
106: * been allocated when creating the contextual object.
107: *
108: * @param userData The contextual object being released.
109: * @param responsePdu The SnmpPduPacket that will be sent back to the
110: * SNMP manager.
111: * <b>This parameter is owned by the SNMP framework and must be
112: * considered as transient.</b> If you wish to keep some of its
113: * content after this method returns you should clone that
114: * information.
115: *
116: * @exception SnmpStatusException If an SnmpStatusException is thrown,
117: * the responsePdu is dropped and nothing is returned to
118: * to the manager.
119: *
120: * @since 1.5
121: **/
122: public void releaseUserData(Object userData, SnmpPdu responsePdu)
123: throws SnmpStatusException;
124: }
|