RetrievalEvent


1   /*_############################################################################
2     _##
3     _##  SNMP4J - RetrievalEvent.java
4     _##
5     _##  Copyright 2003-2007  Frank Fock and Jochen Katz (SNMP4J.org)
6     _##
7     _##  Licensed under the Apache License, Version 2.0 (the "License");
8     _##  you may not use this file except in compliance with the License.
9     _##  You may obtain a copy of the License at
10    _##
11    _##      http://www.apache.org/licenses/LICENSE-2.0
12    _##
13    _##  Unless required by applicable law or agreed to in writing, software
14    _##  distributed under the License is distributed on an "AS IS" BASIS,
15    _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    _##  See the License for the specific language governing permissions and
17    _##  limitations under the License.
18    _##
19    _##########################################################################*/
20  
21  package org.snmp4j.util;
22  
23  import java.util.EventObject  ;
24  import org.snmp4j.PDU;
25  import org.snmp4j.smi.VariableBinding;
26  import java.util.Arrays  ;
27  
28  /**
29   * The <code>RetrievalEvent</code> is an abstract class representing the result
30   * of one or more GET/GETNEXT/GETBULK requests.
31   *
32   * @author Frank Fock
33   * @version 1.8
34   * @since 1.8
35   */
36  public abstract class RetrievalEvent extends EventObject   {
37  
38    /**
39     * Retrieval operation was successfull.
40     */
41    public static final int STATUS_OK = 0;
42    /**
43     * A request to the agent timed out.
44     */
45    public static final int STATUS_TIMEOUT = -1;
46    /**
47     * The agent failed to return the objects in lexicographic order.
48     */
49    public static final int STATUS_WRONG_ORDER = -2;
50    /**
51     * A report has been received from the agent.
52     * @see #getReportPDU()
53     */
54    public static final int STATUS_REPORT = -3;
55    /**
56     * An exception occured during retrieval operation.
57     * @see #getException()
58     */
59    public static final int STATUS_EXCEPTION = -4;
60  
61    protected VariableBinding[] vbs;
62    protected int status = STATUS_OK;
63    protected Object   userObject;
64    protected Exception   exception;
65    protected PDU reportPDU;
66  
67    protected RetrievalEvent(Object   source, Object   userObject) {
68      super(source);
69      this.userObject = userObject;
70    }
71  
72    /**
73     * Creates a retrieval event with a status.
74     * @param source
75     *    the source of the event.
76     * @param userObject
77     *    the user object or <code>null</code>.
78     * @param status
79     *    one of the status constants defined for this object.
80     */
81    public RetrievalEvent(Object   source, Object   userObject, int status) {
82      this(source, userObject);
83      this.status = status;
84    }
85  
86    /**
87     * Creates a retrieval event with an exception.
88     * @param source
89     *    the source of the event.
90     * @param userObject
91     *    the user object or <code>null</code>.
92     * @param exception
93     *    an exception instance.
94     */
95    public RetrievalEvent(Object   source, Object   userObject, Exception   exception) {
96      this(source, userObject);
97      this.exception = exception;
98      this.status = STATUS_EXCEPTION;
99    }
100 
101   /**
102    * Creates a retrieval event with a report PDU.
103    * @param source
104    *    the source of the event.
105    * @param userObject
106    *    the user object or <code>null</code>.
107    * @param report
108    *    a PDU of type {@link PDU#REPORT}.
109    */
110   public RetrievalEvent(Object   source, Object   userObject, PDU report) {
111     this(source, userObject);
112     this.reportPDU = report;
113     this.status = STATUS_REPORT;
114   }
115 
116   /**
117    * Creates a retrieval event with row data.
118    *
119    * @param source
120    *    the source of the event.
121    * @param userObject
122    *    the user object or <code>null</code>.
123    * @param variableBindings
124    *    an array of <code>VariableBinding</code> instances.
125    */
126   public RetrievalEvent(Object   source, Object   userObject,
127                         VariableBinding[] variableBindings) {
128     this(source, userObject);
129     this.vbs = variableBindings;
130   }
131 
132   /**
133    * Gets the status of the table operation.
134    * @return
135    *    one of the status constants defined for this object.
136    *    {@link #STATUS_OK} indicates success, all other values indicate
137    *    failure of the operation.
138    */
139   public int getStatus() {
140     return status;
141   }
142 
143   /**
144    * Indicates whether the event reports an error or not.
145    * @return
146    *    <code>true</code> if the operation failed with an error.
147    */
148   public boolean isError() {
149     return (status != STATUS_OK);
150   }
151 
152   /**
153    * Gets the user object that has been specified by the user when the retrieval
154    * operation that fired this event has been requested.
155    * @return
156    *    an object instance if an user object has been specified or
157    *    <code>null</code> otherwise.
158    */
159   public Object   getUserObject() {
160     return userObject;
161   }
162 
163   /**
164    * Gets the exception associated with this event.
165    * @return
166    *    an Exception instance if there has been an exception instance
167    *    associated with this event ({@link #getStatus()} returns
168    *    {@link #STATUS_EXCEPTION}), or <code>null</code> otherwise.
169    */
170   public Exception   getException() {
171     return exception;
172   }
173 
174   /**
175    * Gets the report PDU associated with this event.
176    * @return
177    *    a <code>ScopedPDU</code> instance if there has been a report PDU
178    *    instance associated with this event ({@link #getStatus()} returns
179    *    {@link #STATUS_REPORT}), or <code>null</code> otherwise.
180    */
181   public PDU getReportPDU() {
182     return reportPDU;
183   }
184 
185   /**
186    * Returns a textual error message for the error.
187    * @return
188    *    an error message or an empty string if no error occurred.
189    */
190   public String   getErrorMessage() {
191     switch (status) {
192       case STATUS_EXCEPTION: {
193         return exception.getMessage();
194       }
195       case STATUS_REPORT: {
196         return "Report: "+reportPDU.get(0);
197       }
198       case STATUS_TIMEOUT: {
199         return "Request timed out.";
200       }
201       case STATUS_WRONG_ORDER: {
202         return "Agent did not return variable bindings in lexicographic order.";
203       }
204       default: {
205         return "";
206       }
207     }
208   }
209 
210   public String   toString() {
211     return getClass().getName()+"[vbs="+Arrays.asList(vbs)+
212         ",status="+status+",exception="+
213         exception+",report="+reportPDU+"]";
214   }
215 
216 }
217
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags