1 /* 2 * Copyright (c) 2001, 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 package com.sun.jmx.snmp.internal; 26 27 import java.net.InetAddress; 28 29 import com.sun.jmx.snmp.SnmpSecurityParameters; 30 import com.sun.jmx.snmp.SnmpTooBigException; 31 import com.sun.jmx.snmp.SnmpStatusException; 32 import com.sun.jmx.snmp.SnmpPdu; 33 import com.sun.jmx.snmp.SnmpMsg; 34 35 import com.sun.jmx.snmp.SnmpUnknownSecModelException; 36 import com.sun.jmx.snmp.SnmpBadSecurityLevelException; 37 38 /** 39 <P> An <CODE>SnmpIncomingRequest</CODE> handles both sides of an incoming SNMP request: 40 <ul> 41 <li> The request. Unmarshalling of the received message. </li> 42 <li> The response. Marshalling of the message to send. </li> 43 </ul> 44 * <p><b>This API is a Sun Microsystems internal API and is subject 45 * to change without notice.</b></p> 46 * @since 1.5 47 */ 48 public interface SnmpIncomingRequest { 49 /** 50 * Once the incoming request decoded, returns the decoded security parameters. 51 * @return The decoded security parameters. 52 */ 53 public SnmpSecurityParameters getSecurityParameters(); 54 /** 55 * Tests if a report is expected. 56 * @return boolean indicating if a report is to be sent. 57 */ 58 public boolean isReport(); 59 /** 60 * Tests if a response is expected. 61 * @return boolean indicating if a response is to be sent. 62 */ 63 public boolean isResponse(); 64 65 /** 66 * Tells this request that no response will be sent. 67 */ 68 public void noResponse(); 69 /** 70 * Gets the incoming request principal. 71 * @return The request principal. 72 **/ 73 public String getPrincipal(); 74 /** 75 * Gets the incoming request security level. This level is defined in {@link com.sun.jmx.snmp.SnmpEngine SnmpEngine}. 76 * @return The security level. 77 */ 78 public int getSecurityLevel(); 79 /** 80 * Gets the incoming request security model. 81 * @return The security model. 82 */ 83 public int getSecurityModel(); 84 /** 85 * Gets the incoming request context name. 86 * @return The context name. 87 */ 88 public byte[] getContextName(); 89 /** 90 * Gets the incoming request context engine Id. 91 * @return The context engine Id. 92 */ 93 public byte[] getContextEngineId(); 94 /** 95 * Gets the incoming request context name used by Access Control Model in order to allow or deny the access to OIDs. 96 */ 97 public byte[] getAccessContext(); 98 /** 99 * Encodes the response message to send and puts the result in the specified byte array. 100 * 101 * @param outputBytes An array to receive the resulting encoding. 102 * 103 * @exception ArrayIndexOutOfBoundsException If the result does not fit 104 * into the specified array. 105 */ 106 public int encodeMessage(byte[] outputBytes) 107 throws SnmpTooBigException; 108 109 /** 110 * Decodes the specified bytes and initializes the request with the incoming message. 111 * 112 * @param inputBytes The bytes to be decoded. 113 * 114 * @exception SnmpStatusException If the specified bytes are not a valid encoding or if the security applied to this request failed and no report is to be sent (typically trap PDU). 115 */ 116 public void decodeMessage(byte[] inputBytes, 117 int byteCount, 118 InetAddress address, 119 int port) 120 throws SnmpStatusException, SnmpUnknownSecModelException, 121 SnmpBadSecurityLevelException; 122 123 /** 124 * Initializes the response to send with the passed Pdu. 125 * <P> 126 * If the encoding length exceeds <CODE>maxDataLength</CODE>, 127 * the method throws an exception. 128 * 129 * @param p The PDU to be encoded. 130 * @param maxDataLength The maximum length permitted for the data field. 131 * 132 * @exception SnmpStatusException If the specified <CODE>pdu</CODE> 133 * is not valid. 134 * @exception SnmpTooBigException If the resulting encoding does not fit 135 * into <CODE>maxDataLength</CODE> bytes. 136 * @exception ArrayIndexOutOfBoundsException If the encoding exceeds 137 * <CODE>maxDataLength</CODE>. 138 */ 139 public SnmpMsg encodeSnmpPdu(SnmpPdu p, 140 int maxDataLength) 141 throws SnmpStatusException, SnmpTooBigException; 142 143 /** 144 * Gets the request PDU encoded in the received message. 145 * <P> 146 * This method decodes the data field and returns the resulting PDU. 147 * 148 * @return The resulting PDU. 149 * @exception SnmpStatusException If the encoding is not valid. 150 */ 151 public SnmpPdu decodeSnmpPdu() 152 throws SnmpStatusException; 153 154 /** 155 * Returns a stringified form of the received message. 156 * @return The message state string. 157 */ 158 public String printRequestMessage(); 159 /** 160 * Returns a stringified form of the message to send. 161 * @return The message state string. 162 */ 163 public String printResponseMessage(); 164 }