KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > jmx > snmp > internal > SnmpEngineImpl


1 /*
2  * @(#)file SnmpEngineImpl.java
3  * @(#)author Sun Microsystems, Inc.
4  * @(#)version 1.45
5  * @(#)date 08/02/09
6  *
7  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
8  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
9  *
10  */

11 package com.sun.jmx.snmp.internal;
12
13 import java.net.InetAddress JavaDoc;
14 import java.net.UnknownHostException JavaDoc;
15 import java.util.Hashtable JavaDoc;
16 import java.io.Serializable JavaDoc;
17
18 import com.sun.jmx.snmp.SnmpDefinitions;
19 import com.sun.jmx.snmp.SnmpEngineId;
20 import com.sun.jmx.snmp.SnmpEngine;
21 import com.sun.jmx.snmp.SnmpUsmKeyHandler;
22 import com.sun.jmx.snmp.SnmpEngineFactory;
23 import com.sun.jmx.snmp.SnmpUnknownModelException;
24
25 import com.sun.jmx.snmp.internal.SnmpTools;
26 import com.sun.jmx.snmp.SnmpBadSecurityLevelException;
27 import com.sun.jmx.trace.Trace;
28 /**
29  * This engine is conformant with the RFC 2571. It is the main object within
30  * an SNMP entity (agent, manager...).
31  * To an engine is associated an {@link com.sun.jmx.snmp.SnmpEngineId}.
32  * The way the engineId is retrieved is linked to the way the engine is
33  * instantiated. See each <CODE>SnmpEngine</CODE> constructor for more details.
34  * An engine is composed of a set of sub systems
35  * {@link com.sun.jmx.snmp.internal.SnmpSubSystem}. An <CODE>SNMP</CODE>
36  * engine can contain a:
37  *<ul>
38  *<li> Message Processing Sub System :
39  * {@link com.sun.jmx.snmp.internal.SnmpMsgProcessingSubSystem}</li>
40  *<li> Security Sub System :
41  * {@link com.sun.jmx.snmp.internal.SnmpSecuritySubSystem} </li>
42  *<li> Access Control Sub System :
43  * {@link com.sun.jmx.snmp.internal.SnmpAccessControlSubSystem}</li>
44  *</ul>
45  *<P> Each sub system contains a set of models. A model is an implementation
46  * of a particular treatement (eg: the User based Security Model defined in
47  * RFC 2574 is a functional element dealing with authentication and privacy).
48  *</P>
49  * Engine instantiation is based on a factory. This factory, implementing
50  * mandatorily {@link com.sun.jmx.snmp.SnmpEngineFactory SnmpEngineFactory}
51  * is set in the method <CODE>setFactory</CODE>.
52  * <p><b>This API is a Sun Microsystems internal API and is subject
53  * to change without notice.</b></p>
54  * @since 1.5
55  */

56 public class SnmpEngineImpl implements SnmpEngine, Serializable JavaDoc {
57     /**
58      * Security level. No authentication, no privacy. Value is 0,
59      * as defined in RFC 2572
60      */

61     public static final int noAuthNoPriv = 0;
62     /**
63      * Security level. Authentication, no privacy. Value is 1, as
64      * defined in RFC 2572
65      */

66     public static final int authNoPriv = 1;
67     /**
68      * Security level. Authentication, privacy. Value is 3,
69      * as defined in RFC 2572
70      */

71     public static final int authPriv = 3;
72     /**
73      * Flag that indicates that a report is to be sent. Value is 4, as defined in RFC 2572
74      */

75     public static final int reportableFlag = 4;
76
77     /**
78      * Mask used to isolate authentication information within a message flag.
79      */

80     public static final int authMask = 1;
81     /**
82      * Mask used to isolate privacy information within a message flag.
83      */

84     public static final int privMask = 2;
85     /**
86      * Mask used to isolate authentication and privacy information within a message flag.
87      */

88     public static final int authPrivMask = 3;
89
90     private SnmpEngineId engineid = null;
91     private SnmpEngineFactory factory = null;
92     private long startTime = 0;
93
94     private int boot = 0;
95     private boolean checkOid = false;
96     
97     transient private SnmpUsmKeyHandler usmKeyHandler = null;
98     transient private SnmpLcd lcd = null;
99
100     transient private SnmpSecuritySubSystem securitySub = null;
101
102     transient private SnmpMsgProcessingSubSystem messageSub = null;
103
104     transient private SnmpAccessControlSubSystem accessSub = null;
105
106     /**
107      * Gets the engine time in seconds. This is the time from the last reboot.
108      * @return The time from the last reboot.
109      */

110     public synchronized int getEngineTime() {
111     //We do the counter wrap in a lazt way. Each time Engine is asked for his time it checks. So if nobody use the Engine, the time can wrap and wrap again without incrementing nb boot. We can imagine that it is irrelevant due to the amount of time needed to wrap.
112
long delta = (System.currentTimeMillis() / 1000) - startTime;
113     if(delta > 0x7FFFFFFF) {
114         //67 years of running. That is a great thing!
115
//Reinitialize startTime.
116
startTime = System.currentTimeMillis() / 1000;
117
118         //Can't do anything with this counter.
119
if(boot != 0x7FFFFFFF)
120         boot += 1;
121         //Store for future use.
122
storeNBBoots(boot);
123     }
124     
125     return (int) ((System.currentTimeMillis() / 1000) - startTime);
126     }
127
128     /**
129      * Gets the engine Id. This is unique for each engine.
130      * @return The engine Id object.
131      */

132     public SnmpEngineId getEngineId() {
133     return engineid;
134     }
135     
136     /**
137      * Gets the Usm key handler.
138      * @return The key handler.
139      */

140     public SnmpUsmKeyHandler getUsmKeyHandler() {
141     return usmKeyHandler;
142     }
143
144     /**
145      * Gets the engine Lcd.
146      * @return The engine Lcd.
147      */

148     public SnmpLcd getLcd() {
149     return lcd;
150     }
151     /**
152      * Gets the engine boot number. This is the number of time this engine has rebooted. Each time an <CODE>SnmpEngine</CODE> is instantiated, it will read this value in its Lcd, and store back the value incremented by one.
153      * @return The engine's number of reboot.
154      */

155     public int getEngineBoots() {
156     return boot;
157     }
158
159      /**
160      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine Id, engine boots).
161      * <P> WARNING : The SnmpEngineId is computed as follow:
162      * <ul>
163      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
164      * <li> If not, if the passed engineID is not null, this engine ID is used.</li>
165      * <li> If not, a time based engineID is computed.</li>
166      * </ul>
167      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
168      * @param fact The factory used to instantiate this engine.
169      * @param lcd The local configuration datastore.
170      * @param engineid The engine ID to use. If null is provided, an SnmpEngineId is computed using the current time.
171      * @throws UnknownHostException Exception thrown, if the host name located in the property "localEngineID" is invalid.
172      */

173     public SnmpEngineImpl(SnmpEngineFactory fact,
174               SnmpLcd lcd,
175               SnmpEngineId engineid) throws UnknownHostException JavaDoc {
176     
177     init(lcd, fact);
178     initEngineID();
179     if(this.engineid == null) {
180         if(engineid != null)
181         this.engineid = engineid;
182         else
183         this.engineid = SnmpEngineId.createEngineId();
184     }
185     lcd.storeEngineId(this.engineid);
186     if(isTraceOn()) {
187         trace("SnmpEngine", "LOCAL ENGINE ID: " + this.engineid);
188     }
189     }
190     /**
191      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine ID, engine boots).
192      * <P> WARNING : The SnmpEngineId is computed as follow:
193      * <ul>
194      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
195      * <li> If not, the passed address and port are used to compute one.</li>
196      * </ul>
197      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
198      * @param fact The factory used to instantiate this engine.
199      * @param lcd The local configuration datastore.
200      * @param port UDP port to use in order to calculate the engine ID.
201      * @param address An IP address used to calculate the engine ID.
202      * @throws UnknownHostException Exception thrown, if the host name located in the property "localEngineID" is invalid.
203      */

204     public SnmpEngineImpl(SnmpEngineFactory fact,
205               SnmpLcd lcd,
206               InetAddress JavaDoc address,
207               int port) throws UnknownHostException JavaDoc {
208     init(lcd, fact);
209     initEngineID();
210     if(engineid == null)
211         engineid = SnmpEngineId.createEngineId(address, port);
212
213     lcd.storeEngineId(engineid);
214     
215     if(isTraceOn()) {
216         trace("SnmpEngine", "LOCAL ENGINE ID: " + engineid + " / " +
217           "LOCAL ENGINE NB BOOTS: " + boot + " / " +
218           "LOCAL ENGINE START TIME: " + getEngineTime());
219     }
220     }
221
222     /**
223      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine ID, engine boots).
224      * <P> WARNING : The SnmpEngineId is computed as follow:
225      * <ul>
226      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
227      * <li> If not, The passed port is used to compute one.</li>
228      * </ul>
229      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
230      * @param fact The factory used to instantiate this engine.
231      * @param lcd The local configuration datastore
232      * @param port UDP port to use in order to calculate the engine ID.
233      * @throws UnknownHostException Exception thrown, if the host name located in the property "localEngineID" is invalid.
234      */

235     public SnmpEngineImpl(SnmpEngineFactory fact,
236               SnmpLcd lcd,
237               int port) throws UnknownHostException JavaDoc {
238     init(lcd, fact);
239     initEngineID();
240     if(engineid == null)
241        engineid = SnmpEngineId.createEngineId(port);
242
243     lcd.storeEngineId(engineid);
244
245     if(isTraceOn()) {
246         trace("SnmpEngine", "LOCAL ENGINE ID: " + engineid + " / " +
247           "LOCAL ENGINE NB BOOTS: " + boot + " / " +
248           "LOCAL ENGINE START TIME: " + getEngineTime());
249     }
250     }
251
252     /**
253      * Constructor. A Local Configuration Datastore is passed to the engine. It will be used to store and retrieve data (engine ID, engine boots).
254      * <P> WARNING : The SnmpEngineId is computed as follow:
255      * <ul>
256      * <li> If an lcd file is provided containing the property "localEngineID", this property value is used.</li>.
257      * <li> If not, a time based engineID is computed.</li>
258      * </ul>
259      * When no configuration nor java property is set for the engine ID value, a unique time based engine ID will be generated.
260      * This constructor should be called by an <CODE>SnmpEngineFactory</CODE>. Don't call it directly.
261      * @param fact The factory used to instantiate this engine.
262      * @param lcd The local configuration datastore.
263      */

264     public SnmpEngineImpl(SnmpEngineFactory fact,
265               SnmpLcd lcd) throws UnknownHostException JavaDoc {
266     init(lcd, fact);
267     initEngineID();
268     if(engineid == null)
269         engineid = SnmpEngineId.createEngineId();
270     
271     lcd.storeEngineId(engineid);
272
273
274     if(isTraceOn()) {
275         trace("SnmpEngine", "LOCAL ENGINE ID: " + engineid + " / " +
276           "LOCAL ENGINE NB BOOTS: " + boot + " / " +
277           "LOCAL ENGINE START TIME: " + getEngineTime());
278     }
279     }
280
281     /**
282      * Access Control will check the oids. By default is false.
283      */

284     public synchronized void activateCheckOid() {
285     checkOid = true;
286     }
287     
288     /**
289      * Access Control will not check the oids. By default is false.
290      */

291     public synchronized void deactivateCheckOid() {
292     checkOid = false;
293     }
294     
295     /**
296      * Access Control check or not the oids. By default is false.
297      */

298     public synchronized boolean isCheckOidActivated() {
299     return checkOid;
300     }
301
302     //Do some check and store the nb boots value.
303
private void storeNBBoots(int boot) {
304     if(boot < 0 || boot == 0x7FFFFFFF) {
305         boot = 0x7FFFFFFF;
306         lcd.storeEngineBoots(boot);
307     }
308     else
309         lcd.storeEngineBoots(boot + 1);
310     }
311
312     // Initialize internal status.
313
private void init(SnmpLcd lcd, SnmpEngineFactory fact) {
314     this.factory = fact;
315     this.lcd = lcd;
316     boot = lcd.getEngineBoots();
317
318     if(boot == -1 || boot == 0)
319         boot = 1;
320
321     storeNBBoots(boot);
322
323     startTime = System.currentTimeMillis() / 1000;
324
325     }
326     
327     void setUsmKeyHandler(SnmpUsmKeyHandler usmKeyHandler) {
328     this.usmKeyHandler = usmKeyHandler;
329     }
330
331     //Initialize the engineID.
332
private void initEngineID() throws UnknownHostException JavaDoc {
333     String JavaDoc id = lcd.getEngineId();
334     if(id != null) {
335         engineid = SnmpEngineId.createEngineId(id);
336     }
337     }
338
339   
340     /**
341      * Returns the Message Processing Sub System.
342      * @return The Message Processing Sub System.
343      */

344     public SnmpMsgProcessingSubSystem getMsgProcessingSubSystem() {
345     return messageSub;
346     }
347
348     /**
349      * Sets the Message Processing Sub System.
350      * @param sys The Message Processing Sub System.
351      */

352     public void setMsgProcessingSubSystem(SnmpMsgProcessingSubSystem sys) {
353     messageSub = sys;
354     }
355     
356      /**
357      * Returns the Security Sub System.
358      * @return The Security Sub System.
359      */

360     public SnmpSecuritySubSystem getSecuritySubSystem() {
361     return securitySub;
362     }
363     /**
364      * Sets the Security Sub System.
365      * @param sys The Security Sub System.
366      */

367     public void setSecuritySubSystem(SnmpSecuritySubSystem sys) {
368     securitySub = sys;
369     }
370      /**
371      * Sets the Access Control Sub System.
372      * @param sys The Access Control Sub System.
373      */

374     public void setAccessControlSubSystem(SnmpAccessControlSubSystem sys) {
375     accessSub = sys;
376     }
377
378     /**
379      * Returns the Access Control Sub System.
380      * @return The Access Control Sub System.
381      */

382     public SnmpAccessControlSubSystem getAccessControlSubSystem() {
383     return accessSub;
384     }
385     /**
386      * Checks the passed msg flags according to the rules specified in RFC 2572.
387      * @param msgFlags The msg flags.
388      */

389     public static void checkSecurityLevel(byte msgFlags)
390     throws SnmpBadSecurityLevelException {
391     int secLevel = msgFlags & SnmpDefinitions.authPriv;
392     if((secLevel & SnmpDefinitions.privMask) != 0)
393         if((secLevel & SnmpDefinitions.authMask) == 0) {
394         throw new SnmpBadSecurityLevelException("Security level:"+
395                             " noAuthPriv!!!");
396         }
397     }
398     
399     // TRACES & DEBUG
400
//---------------
401

402     boolean isTraceOn() {
403         return Trace.isSelected(Trace.LEVEL_TRACE, Trace.INFO_SNMP);
404     }
405
406     void trace(String JavaDoc clz, String JavaDoc func, String JavaDoc info) {
407         Trace.send(Trace.LEVEL_TRACE, Trace.INFO_SNMP, clz, func, info);
408     }
409
410     void trace(String JavaDoc func, String JavaDoc info) {
411         trace(dbgTag, func, info);
412     }
413     
414     boolean isDebugOn() {
415         return Trace.isSelected(Trace.LEVEL_DEBUG, Trace.INFO_SNMP);
416     }
417
418     void debug(String JavaDoc clz, String JavaDoc func, String JavaDoc info) {
419         Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_SNMP, clz, func, info);
420     }
421
422     void debug(String JavaDoc clz, String JavaDoc func, Throwable JavaDoc exception) {
423         Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_SNMP, clz, func, exception);
424     }
425
426     void debug(String JavaDoc func, String JavaDoc info) {
427         debug(dbgTag, func, info);
428     }
429     
430     void debug(String JavaDoc func, Throwable JavaDoc exception) {
431         debug(dbgTag, func, exception);
432     }
433     
434     String JavaDoc dbgTag = "SnmpEngineImpl";
435 }
436
Popular Tags