1 /* 2 * Copyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.jmx.snmp.agent; 27 28 import com.sun.jmx.snmp.SnmpPduPacket; 29 import com.sun.jmx.snmp.SnmpPdu; 30 import com.sun.jmx.snmp.SnmpStatusException; 31 32 /** 33 * This interface is provided to enable fine customization of the SNMP 34 * agent behaviour. 35 * 36 * <p>You will not need to implement this interface except if your agent 37 * needs extra customization requiring some contextual information.</p> 38 * 39 * <p>If an SnmpUserDataFactory is set on the SnmpAdaptorServer, then a new 40 * object containing user-data will be allocated through this factory 41 * for each incoming request. This object will be passed along to 42 * the SnmpMibAgent within SnmpMibRequest objects. By default, no 43 * SnmpUserDataFactory is set on the SnmpAdaptorServer, and the contextual 44 * object passed to SnmpMibAgent is null.</p> 45 * 46 * <p>You can use this feature to obtain on contextual information 47 * (such as community string etc...) or to implement a caching 48 * mechanism, or for whatever purpose might be required by your specific 49 * agent implementation.</p> 50 * 51 * <p>The sequence <code>allocateUserData() / releaseUserData()</code> can 52 * also be used to implement a caching mechanism: 53 * <ul> 54 * <li><code>allocateUserData()</code> could be used to allocate 55 * some cache space,</li> 56 * <li>and <code>releaseUserData()</code> could be used to flush it.</li> 57 * </ul></p> 58 * 59 * <p><b>This API is a Sun Microsystems internal API and is subject 60 * to change without notice.</b></p> 61 * @see com.sun.jmx.snmp.agent.SnmpMibRequest 62 * @see com.sun.jmx.snmp.agent.SnmpMibAgent 63 * @see com.sun.jmx.snmp.daemon.SnmpAdaptorServer 64 * 65 **/ 66 public interface SnmpUserDataFactory { 67 /** 68 * Called by the <CODE>SnmpAdaptorServer</CODE> adaptor. 69 * Allocate a contextual object containing some user data. This method 70 * is called once for each incoming SNMP request. The scope 71 * of this object will be the whole request. Since the request can be 72 * handled in several threads, the user should make sure that this 73 * object can be accessed in a thread-safe manner. The SNMP framework 74 * will never access this object directly - it will simply pass 75 * it to the <code>SnmpMibAgent</code> within 76 * <code>SnmpMibRequest</code> objects - from where it can be retrieved 77 * through the {@link com.sun.jmx.snmp.agent.SnmpMibRequest#getUserData() getUserData()} accessor. 78 * <code>null</code> is considered to be a valid return value. 79 * 80 * This method is called just after the SnmpPduPacket has been 81 * decoded. 82 * 83 * @param requestPdu The SnmpPduPacket received from the SNMP manager. 84 * <b>This parameter is owned by the SNMP framework and must be 85 * considered as transient.</b> If you wish to keep some of its 86 * content after this method returns (by storing it in the 87 * returned object for instance) you should clone that 88 * information. 89 * 90 * @return A newly allocated user-data contextual object, or 91 * <code>null</code> 92 * @exception SnmpStatusException If an SnmpStatusException is thrown, 93 * the request will be aborted. 94 * 95 * @since 1.5 96 **/ 97 public Object allocateUserData(SnmpPdu requestPdu) 98 throws SnmpStatusException; 99 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 }